CMI-Telemetry (OpenTelemetry)

Die CMI-Lösungsplattform, einschliesslich der Mehrheit der CMI-Schnittstellen und CMI-Services, unterstützt den Export von Telemetrie-Daten gemäss dem Standard OpenTelemetry (OTEL). Dabei werden Metriken, Traces und Logs erfasst. In On-Premises-Installationen ist die Telemetrie standardmässig deaktiviert. Wird sie aktiviert, ohne weitere Konfiguration vorzunehmen, werden die Telemetrie-Daten an die Standardadresse http://localhost:4318 gesendet.

Für die Verarbeitung und Nutzung der Telemetrie-Daten ist ein OTEL-kompatibler Collector oder ein entsprechendes Überwachungssystem erforderlich.

Allgemeine Informationen zum Einsatz und der Unterstützung

• Erweiterungen und Anpassungen der Telemetrie-Funktionalität werden in der Online-Dokumentation bekannt gegeben.
• Die Erhebung von Telemetrie-Daten erfolgt primär durch das CMI-Cloud-Team, um zentrale Informationen über den Zustand der CMI-Komponenten für den Betrieb der CMI Cloud bereitzustellen.
• Der Support und die Projektleitenden der CMI bieten keine direkte Unterstützung bei der Einrichtung oder Nutzung von Telemetrie und OpenTelemetry (OTEL). Die Integration erfordert, dass beim Kunden fundierte Kenntnisse in der Erhebung und Verarbeitung von Telemetrie-Daten vorhanden sind und diese eigenständig weiterentwickelt werden können. Während der Initialisierungsphase kann das CMI-Cloud-Team im Rahmen von Dienstleistungen unterstützend tätig werden.
• CMI übernimmt keinen Support für die Konfiguration oder den Betrieb spezifischer Überwachungssysteme.

Aktivierung der Telemetrie am CMI Server

Dieses Kapitel beschreibt, wie die Telemetrie am CMI Server aktiviert wird. Voraussetzung ist Release 25 oder neuer.

1. Erstellen der appsettings.json-Datei

Im Installationsverzeichnis des CMI Servers muss eine Datei mit dem Namen appsettings.json angelegt werden. Um Metriken und Traces zu aktivieren, sind folgende Schlüssel erforderlich:

{
    "EnableCmiTelemetry": true,
    "TenantId": "my tenant id"
}

• EnableCmiTelemetry: Aktiviert die Telemetrie-Funktionalität.
• TenantId: Die Mandanten-ID, die beliebig festgelegt werden kann.

2. Konfiguration von OTEL über Umgebungsvariablen

Die OpenTelemetry-Konfiguration erfolgt über Umgebungsvariablen. Eine Übersicht der verfügbaren Optionen finden Sie unter: OpenTelemetry-Umgebungsvariablen.

Die wichtigsten Einstellungen sind:

• OTEL_EXPORTER_OTLP_ENDPOINT: URL des OTEL Collectors (Standard: http://localhost:4318)
• OTEL_EXPORTER_OTLP_PROTOCOL: Kommunikationsprotokoll (Standard: http/protobuf)

3. Übermittlung von Log-Daten mit Serilog

Um Log-Daten über Telemetrie zu senden, muss Serilog ebenfalls über die Datei appsettings.json konfiguriert werden.

Wichtige Hinweise zur Log-Konfiguration:

• Die direkte Konfiguration von Serilog in der appsettings.json-Datei überschreibt alle Log-Einstellungen, die über die üblichen 'CMI Server'-Einstellungen vorgenommen wurden.
• Der betreuende CMI-Projektleiter muss über die geänderte Log-Konfiguration informiert werden.
• Während eines Supportfalls müssen die Logdaten proaktiv bereitgestellt werden, da der CMI-Support keinen Zugriff auf diese hat.

Die folgende Konfiguration sendet Log-Daten sowohl an einen OTEL-Collector als auch in lokale Log-Dateien:

{
    "Serilog": {
        "Using": [
            "CMI.Logging.Implementation"
        ],
        "MinimumLevel": {
            "Default": "Information"
        },
        "WriteTo": [
            {
                "Name": "OpenTelemetry",
                "Args": {
                    "endpoint": "http://127.0.0.1:4318/v1/logs",
                    "protocol": "HttpProtobuf"
                }
            },
            {
                "Name": "File",
                "Args": {
                    "outputTemplate": "[{Timestamp:dd-MM-yyyy HH:mm:ss.fff} | {Level} | Source:{className}:{sourceLineNumber} | Process:{process} | Thread:{thread}]{objectText}{objectGuid} {Message}{NewLine}{Exception}",
                    "rollingInterval": "Day",
                    "retainedFileCountLimit": 30,
                    "rollOnFileSizeLimit": true,
                    "fileSizeLimitBytes": 524288000,
                    "path": "..\\log\\server-.log"
                }
            }
        ]
    }
}

Details zu den Konfigurationsoptionen finden Sie in der Dokumentation der verwendeten Serilog-Sinks:

• Serilog.Sinks.File
• Serilog.Sinks.OpenTelemetry

Aktivierung der Telemetrie in CMI-Komponenten

In der Mehrheit der CMI-Komponenten ist OpenTelemetry (OTEL) integriert. Dies erkennen Sie daran, dass im Installationsverzeichnis der jeweiligen Komponente die Datei OpenTelemetry.dll vorhanden ist.

Die Aktivierung der Telemetrie erfolgt ebenfalls über die Konfigurationsdatei appsettings.json. Ein Beispiel:

{
  "EnableCmiTelemetry": true,
  "Logging": {
    "OpenTelemetry": {
      "LogLevel": {
        "Default": "Information",
        "Microsoft": "Warning",
        "Microsoft.Hosting.Lifetime": "Information",
        "Microsoft.AspNetCore.HttpLogging.HttpLoggingMiddleware": "Information"
      }
    }
  }
}

Alle weiteren Einstellungen für den Export von Telemetrie-Daten können der offiziellen Dokumentation entnommen werden:

• OTLP Exporter for OpenTelemetry .NET
• OTLP Exporter Configuration

Die Konfiguration erfolgt über Umgebungsvariablen. Nachfolgend die wichtigsten Optionen:

• OTEL_EXPORTER_OTLP_ENDPOINT (URI, Default: http://localhost:4317) Alternativen:
• OTEL_EXPORTER_OTLP_TRACES_ENDPOINT (nur für Traces)
• OTEL_EXPORTER_OTLP_METRICS_ENDPOINT (nur für Metriken)
• OTEL_EXPORTER_OTLP_LOGS_ENDPOINT (nur für Logs)
• OTEL_EXPORTER_OTLP_PROTOCOL (http|gRPC, Default: gRPC)
• OTEL_EXPORTER_OTLP_HEADERS (key=value,key=value)