Rochas.Telemetry 1.1.1

Rochas.Telemetry

English | Português | Español | Français | Deutsch

English

Rochas.Telemetry is a class-level telemetry library for .NET. It lets you instrument any service or component without a heavy setup: wrap a piece of code with a timed observer to measure how long it takes to run, or start a service-level observer that periodically samples the health of your process in real time.

Overview

The library is built around two main types:

• ComponentObserver (implements IComponentObserver)

  • Measures the execution time of any operation through ExecuteTimed.
  • Keeps an in-memory activity history (System.Diagnostics Activity records) when ActivityLog is enabled, exporting the current process activity from which ExportActivityHistory, ActivityHistoryCount and ClearActivityHistory operate.
  • Optionally receives an ILogger for diagnostics, logging errors and debug events.

• ServiceObserver (extends ComponentObserver, implements IServiceObserver)

  • Starts a background observer task with StartObserver(duration, interval) that takes periodic snapshots of the running process.
  • Collects CPU usage, memory (MB), thread count, process uptime, observer instances, errors and recorded operations into a RealtimeSnapshot.
  • Registers process metrics (CPU, memory, threads, uptime, instances, errors) through a System.Diagnostics.Metrics meter.
  • Manages its lifecycle with StartObserver, StopObserver and IsObserverEnabled, and exposes its history through ExportObserverHistory and ClearObserverHistory.
  • Lets you record failures yourself with RegisterError.

• RealtimeSnapshot (Rochas.Telemetry.Helpers)

  • A plain data class representing one sample taken by the ServiceObserver, with Timestamp, CpuPercent, Memory, Threads, Uptime, Instances, Operations and Errors.

Features

• Class-level, component-scoped telemetry with no external infrastructure required.
• Timed execution of both Func<Task> and Func<Task<TResult>> operations.
• Activity history with call time and error tags, exportable on demand.
• Real-time service health snapshots for CPU, memory, threads and uptime.
• Counts of observer instances, recorded operations and registered errors.
• Optional ILogger integration for error and debug logging.
• Targets netstandard2.1, so it runs on .NET Core, .NET 5+ and later frameworks.

Installation

Add the package to your project with the .NET CLI:

dotnet add package Rochas.Telemetry

Quick Start

Timed component operations

Measure how long an operation takes and keep its activity in the history:

using System;
using System.Threading.Tasks;
using Microsoft.Extensions.Logging.Abstractions;
using Rochas.Telemetry;

public class OrderService
{
    private readonly ComponentObserver _observer =
        new ComponentObserver("OrderService", NullLogger.Instance);

    public async Task<Guid> CreateOrderAsync()
    {
        return await _observer.ExecuteTimed("CreateOrder", async () =>
        {
            await Task.Delay(120);
            return Guid.NewGuid();
        });
    }

    public int RecordedActivities => _observer.ActivityHistoryCount();

    public void ExportActivities() => _observer.ExportActivityHistory();
}

The ILogger parameter is optional. When passed, the observer logs debug events and error summaries through it.

Real-time service snapshots

Start a ServiceObserver that samples the process health every few minutes and inspect the snapshots as they accumulate:

using System;
using System.Threading.Tasks;
using Microsoft.Extensions.Logging.Abstractions;
using Rochas.Telemetry;

var observer = new ServiceObserver("CheckoutWorker", NullLogger.Instance);
observer.StartObserver(duration: 60, interval: 5);

while (observer.IsObserverEnabled())
{
    foreach (var snap in observer.ExportObserverHistory())
    {
        Console.WriteLine(
            $"CPU {snap.CpuPercent}% | Mem {snap.Memory} MB | " +
            $"Threads {snap.Threads} | Uptime {snap.Uptime}s | " +
            $"Operations {snap.Operations} | Errors {snap.Errors}");
    }

    await Task.Delay(TimeSpan.FromSeconds(10));
}

observer.StopObserver();

StartObserver receives duration and interval in minutes. While the observer is enabled, each snapshot is appended to its history and can be read or exported with ExportObserverHistory.

License

Licensed under the GNU General Public License v2. See the LICENSE file.

Português

Rochas.Telemetry é uma biblioteca de telemetria em nível de classe para .NET. Ela permite instrumentar qualquer serviço ou componente sem configuração pesada: envolva um trecho de código com um observador temporizado para medir quanto tempo leva para executar, ou inicie um observador de nível de serviço que amostra periodicamente a saúde do seu processo em tempo real.

Visão geral

A biblioteca é construída em torno de dois tipos principais:

• ComponentObserver (implementa IComponentObserver)

  • Mede o tempo de execução de qualquer operação através de ExecuteTimed.
  • Mantém um histórico de atividades em memória (registros Activity do System.Diagnostics) quando ActivityLog está habilitado, e a partir dele operam ExportActivityHistory, ActivityHistoryCount e ClearActivityHistory.
  • Opcionalmente recebe um ILogger para diagnósticos, registrando erros e eventos de depuração.

• ServiceObserver (estende ComponentObserver, implementa IServiceObserver)

  • Inicia uma tarefa de observação em segundo plano com StartObserver(duration, interval) que coleta amostras periódicas do processo em execução.
  • Coleta uso de CPU, memória (MB), quantidade de threads, tempo de atividade do processo, instâncias do observador, erros e operações registradas em um RealtimeSnapshot.
  • Registra métricas do processo (CPU, memória, threads, uptime, instâncias, erros) por meio de um medidor System.Diagnostics.Metrics.
  • Gerencia seu ciclo de vida com StartObserver, StopObserver e IsObserverEnabled, e expõe seu histórico por ExportObserverHistory e ClearObserverHistory.
  • Permite registrar falhas manualmente com RegisterError.

• RealtimeSnapshot (Rochas.Telemetry.Helpers)

  • Uma classe de dados simples que representa uma amostra coletada pelo ServiceObserver, com Timestamp, CpuPercent, Memory, Threads, Uptime, Instances, Operations e Errors.

Recursos

• Telemetria em nível de classe e escopo de componente, sem infraestrutura externa.
• Execução temporizada de operações Func<Task> e Func<Task<TResult>>.
• Histórico de atividades com tags de tempo de chamada e erro, exportável sob demanda.
• Snapshots em tempo real da saúde do serviço: CPU, memória, threads e uptime.
• Contadores de instâncias do observador, operações registradas e erros.
• Integração opcional com ILogger para registro de erros e depuração.
• Compatível com netstandard2.1, roda no .NET Core, .NET 5+ e versões posteriores.

Instalação

Adicione o pacote ao seu projeto com a CLI do .NET:

dotnet add package Rochas.Telemetry

Início rápido

Operações de componente temporizadas

Meça quanto tempo uma operação leva e mantenha sua atividade no histórico:

using System;
using System.Threading.Tasks;
using Microsoft.Extensions.Logging.Abstractions;
using Rochas.Telemetry;

public class OrderService
{
    private readonly ComponentObserver _observer =
        new ComponentObserver("OrderService", NullLogger.Instance);

    public async Task<Guid> CreateOrderAsync()
    {
        return await _observer.ExecuteTimed("CreateOrder", async () =>
        {
            await Task.Delay(120);
            return Guid.NewGuid();
        });
    }

    public int RecordedActivities => _observer.ActivityHistoryCount();

    public void ExportActivities() => _observer.ExportActivityHistory();
}

O parâmetro ILogger é opcional. Quando informado, o observador registra eventos de depuração e resumos de erro através dele.

Snapshots de serviço em tempo real

Inicie um ServiceObserver que amostra a saúde do processo a cada poucos minutos e inspecione os snapshots à medida que eles se acumulam:

using System;
using System.Threading.Tasks;
using Microsoft.Extensions.Logging.Abstractions;
using Rochas.Telemetry;

var observer = new ServiceObserver("CheckoutWorker", NullLogger.Instance);
observer.StartObserver(duration: 60, interval: 5);

while (observer.IsObserverEnabled())
{
    foreach (var snap in observer.ExportObserverHistory())
    {
        Console.WriteLine(
            $"CPU {snap.CpuPercent}% | Mem {snap.Memory} MB | " +
            $"Threads {snap.Threads} | Uptime {snap.Uptime}s | " +
            $"Operations {snap.Operations} | Errors {snap.Errors}");
    }

    await Task.Delay(TimeSpan.FromSeconds(10));
}

observer.StopObserver();

StartObserver recebe duration e interval em minutos. Enquanto o observador está habilitado, cada snapshot é adicionado ao histórico e pode ser lido ou exportado com ExportObserverHistory.

Licença

Licenciado sob a GNU General Public License v2. Consulte o arquivo LICENSE.

Español

Rochas.Telemetry es una biblioteca de telemetría a nivel de clase para .NET. Permite instrumentar cualquier servicio o componente sin configuración pesada: envuelva un fragmento de código con un observador temporizado para medir cuánto tarda en ejecutarse, o inicie un observador a nivel de servicio que muestree periódicamente la salud de su proceso en tiempo real.

Descripción general

La biblioteca se construye en torno a dos tipos principales:

• ComponentObserver (implementa IComponentObserver)

  • Mide el tiempo de ejecución de cualquier operación mediante ExecuteTimed.
  • Mantiene un historial de actividades en memoria (registros Activity de System.Diagnostics) cuando ActivityLog está habilitado; de él dependen ExportActivityHistory, ActivityHistoryCount y ClearActivityHistory.
  • Recibe opcionalmente un ILogger para diagnósticos, registrando errores y eventos de depuración.

• ServiceObserver (extiende ComponentObserver, implementa IServiceObserver)

  • Inicia una tarea de observación en segundo plano con StartObserver(duration, interval) que toma muestras periódicas del proceso en ejecución.
  • Recopila uso de CPU, memoria (MB), número de subprocesos (threads), tiempo de actividad del proceso, instancias del observador, errores y operaciones registradas en un RealtimeSnapshot.
  • Registra métricas del proceso (CPU, memoria, threads, uptime, instancias, errores) mediante un medidor de System.Diagnostics.Metrics.
  • Gestiona su ciclo de vida con StartObserver, StopObserver e IsObserverEnabled, y expone su historial mediante ExportObserverHistory y ClearObserverHistory.
  • Permite registrar fallos manualmente con RegisterError.

• RealtimeSnapshot (Rochas.Telemetry.Helpers)

  • Una clase de datos simple que representa una muestra tomada por el ServiceObserver, con Timestamp, CpuPercent, Memory, Threads, Uptime, Instances, Operations y Errors.

Características

• Telemetría a nivel de clase y ámbito de componente, sin infraestructura externa.
• Ejecución temporizada de operaciones Func<Task> y Func<Task<TResult>>.
• Historial de actividades con etiquetas de tiempo de llamada y error, exportable a petición.
• Instantáneas en tiempo real de la salud del servicio: CPU, memoria, threads y uptime.
• Recuento de instancias del observador, operaciones registradas y errores.
• Integración opcional con ILogger para registro de errores y depuración.
• Compatible con netstandard2.1: se ejecuta en .NET Core, .NET 5+ y versiones posteriores.

Instalación

Agregue el paquete a su proyecto con la CLI de .NET:

dotnet add package Rochas.Telemetry

Inicio rápido

Operaciones de componente temporizadas

Mida cuánto tarda una operación y conserve su actividad en el historial:

using System;
using System.Threading.Tasks;
using Microsoft.Extensions.Logging.Abstractions;
using Rochas.Telemetry;

public class OrderService
{
    private readonly ComponentObserver _observer =
        new ComponentObserver("OrderService", NullLogger.Instance);

    public async Task<Guid> CreateOrderAsync()
    {
        return await _observer.ExecuteTimed("CreateOrder", async () =>
        {
            await Task.Delay(120);
            return Guid.NewGuid();
        });
    }

    public int RecordedActivities => _observer.ActivityHistoryCount();

    public void ExportActivities() => _observer.ExportActivityHistory();
}

El parámetro ILogger es opcional. Cuando se proporciona, el observador registra eventos de depuración y resúmenes de errores a través de él.

Instantáneas de servicio en tiempo real

Inicie un ServiceObserver que muestree la salud del proceso cada pocos minutos e inspeccione las instantáneas a medida que se acumulan:

using System;
using System.Threading.Tasks;
using Microsoft.Extensions.Logging.Abstractions;
using Rochas.Telemetry;

var observer = new ServiceObserver("CheckoutWorker", NullLogger.Instance);
observer.StartObserver(duration: 60, interval: 5);

while (observer.IsObserverEnabled())
{
    foreach (var snap in observer.ExportObserverHistory())
    {
        Console.WriteLine(
            $"CPU {snap.CpuPercent}% | Mem {snap.Memory} MB | " +
            $"Threads {snap.Threads} | Uptime {snap.Uptime}s | " +
            $"Operations {snap.Operations} | Errors {snap.Errors}");
    }

    await Task.Delay(TimeSpan.FromSeconds(10));
}

observer.StopObserver();

StartObserver recibe duration e interval en minutos. Mientras el observador está habilitado, cada instantánea se añade a su historial y puede leerse o exportarse con ExportObserverHistory.

Licencia

Licenciado bajo la GNU General Public License v2. Consulte el archivo LICENSE.

Français

Rochas.Telemetry est une bibliothèque de télémétrie au niveau des classes pour .NET. Elle permet d'instrumenter n'importe quel service ou composant sans configuration lourde : enveloppez un morceau de code dans un observateur chronométré pour mesurer son temps d'exécution, ou démarrez un observateur au niveau du service qui échantillonne régulièrement la santé de votre processus en temps réel.

Présentation générale

La bibliothèque repose sur deux types principaux :

• ComponentObserver (implémente IComponentObserver)

  • Mesure le temps d'exécution de toute opération via ExecuteTimed.
  • Maintient un historique d'activités en mémoire (enregistrements Activity du System.Diagnostics) lorsque ActivityLog est activé ; ExportActivityHistory, ActivityHistoryCount et ClearActivityHistory opèrent sur cet historique.
  • Accepte optionnellement un ILogger pour les diagnostics, en journalisant les erreurs et les événements de débogage.

• ServiceObserver (étend ComponentObserver, implémente IServiceObserver)

  • Démarre une tâche d'observation en arrière-plan avec StartObserver(duration, interval) qui collecte périodiquement des échantillons du processus en cours.
  • Recueille l'utilisation du CPU, la mémoire (Mo), le nombre de threads, la durée d'activité du processus, les instances de l'observateur, les erreurs et les opérations enregistrées dans un RealtimeSnapshot.
  • Enregistre les métriques du processus (CPU, mémoire, threads, uptime, instances, erreurs) via un compteur System.Diagnostics.Metrics.
  • Gère son cycle de vie avec StartObserver, StopObserver et IsObserverEnabled, et expose son historique via ExportObserverHistory et ClearObserverHistory.
  • Permet d'enregistrer manuellement les échecs avec RegisterError.

• RealtimeSnapshot (Rochas.Telemetry.Helpers)

  • Une classe de données simple représentant un échantillon collecté par le ServiceObserver, avec Timestamp, CpuPercent, Memory, Threads, Uptime, Instances, Operations et Errors.

Fonctionnalités

• Télémétrie au niveau des classes, à portée de composant, sans infrastructure externe.
• Exécution chronométrée des opérations Func<Task> et Func<Task<TResult>>.
• Historique d'activités avec balises de temps d'appel et d'erreur, exportable à la demande.
• Captures en temps réel de la santé du service : CPU, mémoire, threads et uptime.
• Compteurs d'instances de l'observateur, d'opérations enregistrées et d'erreurs.
• Intégration optionnelle de ILogger pour la journalisation des erreurs et du débogage.
• Cible netstandard2.1, compatible avec .NET Core, .NET 5+ et les versions ultérieures.

Installation

Ajoutez le package à votre projet avec l'interface CLI .NET :

dotnet add package Rochas.Telemetry

Démarrage rapide

Opérations de composant chronométrées

Mesurez la durée d'une opération et conservez son activité dans l'historique :

using System;
using System.Threading.Tasks;
using Microsoft.Extensions.Logging.Abstractions;
using Rochas.Telemetry;

public class OrderService
{
    private readonly ComponentObserver _observer =
        new ComponentObserver("OrderService", NullLogger.Instance);

    public async Task<Guid> CreateOrderAsync()
    {
        return await _observer.ExecuteTimed("CreateOrder", async () =>
        {
            await Task.Delay(120);
            return Guid.NewGuid();
        });
    }

    public int RecordedActivities => _observer.ActivityHistoryCount();

    public void ExportActivities() => _observer.ExportActivityHistory();
}

Le paramètre ILogger est facultatif. Lorsqu'il est fourni, l'observateur journalise les événements de débogage et les résumés d'erreurs à travers lui.

Captures de service en temps réel

Démarrez un ServiceObserver qui échantillonne la santé du processus toutes les quelques minutes et inspectez les captures au fur et à mesure qu'elles s'accumulent :

using System;
using System.Threading.Tasks;
using Microsoft.Extensions.Logging.Abstractions;
using Rochas.Telemetry;

var observer = new ServiceObserver("CheckoutWorker", NullLogger.Instance);
observer.StartObserver(duration: 60, interval: 5);

while (observer.IsObserverEnabled())
{
    foreach (var snap in observer.ExportObserverHistory())
    {
        Console.WriteLine(
            $"CPU {snap.CpuPercent}% | Mem {snap.Memory} MB | " +
            $"Threads {snap.Threads} | Uptime {snap.Uptime}s | " +
            $"Operations {snap.Operations} | Errors {snap.Errors}");
    }

    await Task.Delay(TimeSpan.FromSeconds(10));
}

observer.StopObserver();

StartObserver reçoit duration et interval en minutes. Tant que l'observateur est activé, chaque échantillon est ajouté à son historique et peut être lu ou exporté avec ExportObserverHistory.

Licence

Sous licence GNU General Public License v2. Voir le fichier LICENSE.

Deutsch

Rochas.Telemetry ist eine Telemetriebibliothek auf Klassenebene für .NET. Damit können Sie jeden Dienst oder jede Komponente ohne aufwendige Einrichtung instrumentieren: Wickeln Sie einen Codeteil in einen zeitgesteuerten Observer ein, um zu messen, wie lange die Ausführung dauert, oder starten Sie einen Observer auf Dienstebene, der die Gesundheit Ihres Prozesses in Echtzeit in regelmäßigen Abständen erfasst.

Überblick

Die Bibliothek basiert auf zwei Haupttypen:

• ComponentObserver (implementiert IComponentObserver)

  • Misst die Ausführungszeit jeder Operation über ExecuteTimed.
  • Führt einen In-Memory-Aktivitätsverlauf (System.Diagnostics Activity-Datensätze), wenn ActivityLog aktiviert ist; darauf wirken ExportActivityHistory, ActivityHistoryCount und ClearActivityHistory.
  • Nimmt optional einen ILogger für Diagnosezwecke entgegen und protokolliert Fehler und Debug-Ereignisse darüber.

• ServiceObserver (erweitert ComponentObserver, implementiert IServiceObserver)

  • Startet eine Hintergrund-Observer-Task mit StartObserver(duration, interval), die in regelmäßigen Abständen Stichproben des laufenden Prozesses erfasst.
  • Sammelt CPU-Auslastung, Speicher (MB), Anzahl der Threads, Prozesslaufzeit, Observer-Instanzen, Fehler und aufgezeichnete Operationen in einem RealtimeSnapshot.
  • Registriert Prozessmetriken (CPU, Speicher, Threads, Uptime, Instanzen, Fehler) über einen System.Diagnostics.Metrics-Meter.
  • Verwaltet seinen Lebenszyklus mit StartObserver, StopObserver und IsObserverEnabled und stellt seinen Verlauf über ExportObserverHistory und ClearObserverHistory bereit.
  • Ermöglicht es Ihnen, Fehler selbst über RegisterError zu erfassen.

• RealtimeSnapshot (Rochas.Telemetry.Helpers)

  • Eine einfache Datenklasse, die eine vom ServiceObserver erfasste Stichprobe darstellt, mit Timestamp, CpuPercent, Memory, Threads, Uptime, Instances, Operations und Errors.

Funktionen

• Telemetrie auf Klassenebene mit Komponentenbezug, ohne externe Infrastruktur.
• Zeitgesteuerte Ausführung von Func<Task>- und Func<Task<TResult>>-Operationen.
• Aktivitätsverlauf mit Tags für Aufrufzeit und Fehler, auf Wunsch exportierbar.
• Echtzeit-Snapshots der Dienstgesundheit: CPU, Speicher, Threads und Uptime.
• Zähler für Observer-Instanzen, aufgezeichnete Operationen und erfasste Fehler.
• Optionale ILogger-Integration für Fehler- und Debug-Protokollierung.
• Zielplattform netstandard2.1, läuft daher auf .NET Core, .NET 5+ und späteren Frameworks.

Installation

Fügen Sie das Paket über die .NET CLI zu Ihrem Projekt hinzu:

dotnet add package Rochas.Telemetry

Schnellstart

Zeitgesteuerte Komponentenoperationen

Messen Sie, wie lange eine Operation dauert, und behalten Sie ihre Aktivität im Verlauf:

using System;
using System.Threading.Tasks;
using Microsoft.Extensions.Logging.Abstractions;
using Rochas.Telemetry;

public class OrderService
{
    private readonly ComponentObserver _observer =
        new ComponentObserver("OrderService", NullLogger.Instance);

    public async Task<Guid> CreateOrderAsync()
    {
        return await _observer.ExecuteTimed("CreateOrder", async () =>
        {
            await Task.Delay(120);
            return Guid.NewGuid();
        });
    }

    public int RecordedActivities => _observer.ActivityHistoryCount();

    public void ExportActivities() => _observer.ExportActivityHistory();
}

Der ILogger-Parameter ist optional. Wird er übergeben, protokolliert der Observer Debug-Ereignisse und Fehlerzusammenfassungen darüber.

Echtzeit-Snapshots des Dienstes

Starten Sie einen ServiceObserver, der die Gesundheit des Prozesses alle paar Minuten erfasst, und prüfen Sie die Snapshots, während sie sich ansammeln:

using System;
using System.Threading.Tasks;
using Microsoft.Extensions.Logging.Abstractions;
using Rochas.Telemetry;

var observer = new ServiceObserver("CheckoutWorker", NullLogger.Instance);
observer.StartObserver(duration: 60, interval: 5);

while (observer.IsObserverEnabled())
{
    foreach (var snap in observer.ExportObserverHistory())
    {
        Console.WriteLine(
            $"CPU {snap.CpuPercent}% | Mem {snap.Memory} MB | " +
            $"Threads {snap.Threads} | Uptime {snap.Uptime}s | " +
            $"Operations {snap.Operations} | Errors {snap.Errors}");
    }

    await Task.Delay(TimeSpan.FromSeconds(10));
}

observer.StopObserver();

StartObserver erwartet duration und interval in Minuten. Solange der Observer aktiviert ist, wird jede Stichprobe an seinen Verlauf angehängt und kann mit ExportObserverHistory gelesen oder exportiert werden.

Lizenz

Lizenziert unter der GNU General Public License v2. Siehe Datei LICENSE.