> For the complete documentation index, see [llms.txt](https://docs.devolutions.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.devolutions.net/powershell-universal/de/plattform/plugins/opentelemetry.md).

# OpenTelemetry

Konfigurieren Sie das OpenTelemetry-Plug-in, um Metriken und Traces von PowerShell Universal zu exportieren, einschließlich Telemetrie für benutzerdefinierte API-Endpunkte.

**Identifier:** `PowerShellUniversal.Plugins.OpenTelemetry`

Das OpenTelemetry-Plug-in exportiert Metriken von PowerShell Universal und ASP.NET Core-Traces über OTLP. Verwenden Sie einen OpenTelemetry-kompatiblen Collector, ein Dashboard oder ein Metrik-Backend, um Plattformaktivitäten und Anfragen an benutzerdefinierte API-Endpunkte zu untersuchen.

## Plug-in aktivieren

Fügen Sie den exakten, vollqualifizierten Plug-in-Identifier dem Array `Plugins` in `appsettings.json` hinzu. Der Standard-Persistenzanbieter ist SQLite.

```json
{
  "Plugins": [
    "PowerShellUniversal.SQLite",
    "PowerShellUniversal.Plugins.OpenTelemetry"
  ]
}
```

{% hint style="warning" %}
Der Kurzname `OpenTelemetry` und der Assemblyname `PowerShellUniversal.Plugin.OpenTelemetry` aktivieren das Plug-in nicht. Verwenden Sie `PowerShellUniversal.Plugins.OpenTelemetry` genau wie oben dargestellt.
{% endhint %}

Konfigurieren Sie den OTLP-Endpunkt und starten Sie PowerShell Universal neu, nachdem Sie Plug-in- oder Telemetrie-Einstellungen geändert haben.

## OTLP-Export konfigurieren

Setzen Sie `OpenTelemetry:Otlp:Endpoint`, um einen Endpunkt sowohl für Metriken als auch für Traces zu verwenden. Wenn der Fallback-Endpunkt auf `/v1/metrics` endet, verwendet PowerShell Universal diese URL für Metriken und automatisch die entsprechende `/v1/traces`-URL für Traces.

```json
{
  "OpenTelemetry": {
    "Otlp": {
      "Endpoint": "http://localhost:4318/v1/metrics"
    }
  }
}
```

Um separate Collectors oder Endpunkte zu verwenden, konfigurieren Sie die signalspezifischen Einstellungen. Diese Einstellungen überschreiben den Fallback-Endpunkt für die jeweiligen Signale.

```json
{
  "OpenTelemetry": {
    "ServiceName": "PowerShellUniversal-Production",
    "Otlp": {
      "MetricsEndpoint": "http://metrics-collector:4318/v1/metrics",
      "TracesEndpoint": "http://traces-collector:4318/v1/traces"
    }
  }
}
```

Der Standard-Dienstname ist `PowerShellUniversal`. OTLP verwendet standardmäßig HTTP/protobuf. Um das Protokoll explizit festzulegen, setzen Sie `OTEL_EXPORTER_OTLP_PROTOCOL` auf den .NET-Enum-Namen `HttpProtobuf` oder `Grpc`.

{% hint style="warning" %}
Verwenden Sie nicht den Wert `http/protobuf` aus der OpenTelemetry-Spezifikation für `OTEL_EXPORTER_OTLP_PROTOCOL`. PowerShell Universal bindet diese Einstellung direkt an das .NET-Enum `OtlpExportProtocol`, sodass `http/protobuf` einen Konfigurationsfehler beim Start verursacht. Verwenden Sie stattdessen `HttpProtobuf`.
{% endhint %}

## Telemetrie für benutzerdefinierte API-Endpunkte

Das Plug-in instrumentiert Anfragen an benutzerdefinierte API-Endpunkte, einschließlich konventioneller Endpunkte und solcher mit regulären Ausdrücken. Jede Anfrage erzeugt einen ASP.NET Core-Trace-Span, der nach der HTTP-Methode und der Endpunktdefinition benannt ist, etwa `GET /users/{id}`.

Endpunkt-Spans enthalten diese Attribute:

| Attribut                    | Beschreibung                                                  |
| --------------------------- | ------------------------------------------------------------- |
| `http.route`                | Die konfigurierte Endpunkt-URL oder das konfigurierte Muster. |
| `psu.endpoint.id`           | Die Endpunkt-ID von PowerShell Universal.                     |
| `psu.endpoint.url`          | Die konfigurierte Endpunkt-URL oder das konfigurierte Muster. |
| `http.response.status_code` | Der vom Endpunkt zurückgegebene HTTP-Statuscode.              |

Verwenden Sie diese Attribute, um Traces für einen bestimmten Endpunkt oder Antwortstatus in Ihrem Telemetrie-Backend zu filtern.

Das Plug-in exportiert außerdem Endpunkt-Metriken über den Meter `PSU.Endpoints`:

* `PSU.Endpoint.Execution.Count`
* `PSU.Endpoint.Execution.Duration` in Millisekunden
* `PSU.Endpoint.Execution.IncomingContentLength` in Bytes
* `PSU.Endpoint.Execution.OutgoingContentLength` in Bytes

## Prometheus-Metriken

Prometheus kann OTLP-Metriken empfangen, wenn sein OTLP-Receiver aktiviert ist.

```powershell
.\prometheus.exe --web.enable-otlp-receiver
```

Konfigurieren Sie den Metrik-Endpunkt mit der OTLP-Metrik-URL von Prometheus. Prometheus ist ein Metrik-Backend; konfigurieren Sie einen Trace-fähigen Collector oder ein Trace-fähiges Backend separat, wenn Sie auch Traces exportieren möchten.

```json
{
  "OpenTelemetry": {
    "Otlp": {
      "MetricsEndpoint": "http://localhost:9090/api/v1/otlp/v1/metrics"
    }
  }
}
```

## Umgebungsvariablen

Verwenden Sie doppelte Unterstriche für verschachtelte Konfigurationsschlüssel und nullbasierte Indizes für das Array `Plugins`. Dieses Docker Compose-Beispiel aktiviert das Plug-in und exportiert Metriken und Traces über HTTP/protobuf:

```yaml
environment:
  Plugins__1: PowerShellUniversal.Plugins.OpenTelemetry
  OpenTelemetry__Otlp__Endpoint: http://collector:4318/v1/metrics
  OTEL_EXPORTER_OTLP_PROTOCOL: HttpProtobuf
```

Sie können auch signalspezifische Endpunkte konfigurieren:

```
OpenTelemetry__Otlp__MetricsEndpoint=http://metrics-collector:4318/v1/metrics
OpenTelemetry__Otlp__TracesEndpoint=http://traces-collector:4318/v1/traces
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.devolutions.net/powershell-universal/de/plattform/plugins/opentelemetry.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.