> 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/it/piattaforma/plugins/opentelemetry.md). # OpenTelemetry Configuri il plugin OpenTelemetry per esportare metriche e tracce di PowerShell Universal, inclusa la telemetria degli endpoint API personalizzati. **Identificatore:** `PowerShellUniversal.Plugins.OpenTelemetry` Il plugin OpenTelemetry esporta le metriche di PowerShell Universal e le tracce di ASP.NET Core tramite OTLP. Utilizzi un collector, una dashboard o un backend di metriche compatibile con OpenTelemetry per esaminare l'attività della piattaforma e le richieste agli endpoint API personalizzati. ## Abilitare il plugin Aggiunga l'identificatore esatto e completo del plugin all'array `Plugins` in `appsettings.json`. Il provider di persistenza predefinito è SQLite. ```json { "Plugins": [ "PowerShellUniversal.SQLite", "PowerShellUniversal.Plugins.OpenTelemetry" ] } ``` {% hint style="warning" %} Il nome breve `OpenTelemetry` e il nome dell'assembly `PowerShellUniversal.Plugin.OpenTelemetry` non abilitano il plugin. Utilizzi `PowerShellUniversal.Plugins.OpenTelemetry` esattamente come mostrato sopra. {% endhint %} Configuri l'endpoint OTLP e riavvii PowerShell Universal dopo aver modificato le impostazioni del plugin o della telemetria. ## Configurare l'esportazione OTLP Imposti `OpenTelemetry:Otlp:Endpoint` per utilizzare un unico endpoint sia per le metriche sia per le tracce. Se l'endpoint di fallback termina con `/v1/metrics`, PowerShell Universal utilizza tale URL per le metriche e automaticamente l'URL `/v1/traces` corrispondente per le tracce. ```json { "OpenTelemetry": { "Otlp": { "Endpoint": "http://localhost:4318/v1/metrics" } } } ``` Per utilizzare collector o endpoint separati, configuri le impostazioni specifiche per ciascun segnale. Queste impostazioni sovrascrivono l'endpoint di fallback per i rispettivi segnali. ```json { "OpenTelemetry": { "ServiceName": "PowerShellUniversal-Production", "Otlp": { "MetricsEndpoint": "http://metrics-collector:4318/v1/metrics", "TracesEndpoint": "http://traces-collector:4318/v1/traces" } } } ``` Il nome del servizio predefinito è `PowerShellUniversal`. OTLP utilizza HTTP/protobuf per impostazione predefinita. Per impostare il protocollo in modo esplicito, imposti `OTEL_EXPORTER_OTLP_PROTOCOL` sul nome dell'enum .NET `HttpProtobuf` o `Grpc`. {% hint style="warning" %} Non utilizzi il valore della specifica OpenTelemetry `http/protobuf` per `OTEL_EXPORTER_OTLP_PROTOCOL`. PowerShell Universal associa questa impostazione direttamente all'enum .NET `OtlpExportProtocol`, quindi `http/protobuf` provoca un errore di configurazione all'avvio. Utilizzi invece `HttpProtobuf`. {% endhint %} ## Telemetria degli endpoint API personalizzati Il plugin strumenta le richieste agli endpoint API personalizzati, inclusi gli endpoint convenzionali e quelli basati su espressioni regolari. Ogni richiesta produce uno span di traccia ASP.NET Core denominato con il metodo HTTP e la definizione dell'endpoint, ad esempio `GET /users/{id}`. Gli span degli endpoint includono questi attributi: | Attributo | Descrizione | | --------------------------- | ------------------------------------------------- | | `http.route` | L'URL o il pattern dell'endpoint configurato. | | `psu.endpoint.id` | L'ID dell'endpoint di PowerShell Universal. | | `psu.endpoint.url` | L'URL o il pattern dell'endpoint configurato. | | `http.response.status_code` | Il codice di stato HTTP restituito dall'endpoint. | Utilizzi questi attributi per filtrare le tracce di un endpoint specifico o di uno stato di risposta nel suo backend di telemetria. Il plugin esporta anche le metriche degli endpoint tramite il meter `PSU.Endpoints`: * `PSU.Endpoint.Execution.Count` * `PSU.Endpoint.Execution.Duration` in millisecondi * `PSU.Endpoint.Execution.IncomingContentLength` in byte * `PSU.Endpoint.Execution.OutgoingContentLength` in byte ## Metriche Prometheus Prometheus può ricevere metriche OTLP quando il suo ricevitore OTLP è abilitato. ```powershell .\prometheus.exe --web.enable-otlp-receiver ``` Configuri l'endpoint delle metriche con l'URL delle metriche OTLP di Prometheus. Prometheus è un backend di metriche; configuri separatamente un collector o un backend in grado di gestire le tracce quando desidera esportare anche le tracce. ```json { "OpenTelemetry": { "Otlp": { "MetricsEndpoint": "http://localhost:9090/api/v1/otlp/v1/metrics" } } } ``` ## Variabili d'ambiente Utilizzi doppi trattini bassi per le chiavi di configurazione nidificate e indici a base zero per l'array `Plugins`. Questo esempio di Docker Compose abilita il plugin ed esporta metriche e tracce tramite HTTP/protobuf: ```yaml environment: Plugins__1: PowerShellUniversal.Plugins.OpenTelemetry OpenTelemetry__Otlp__Endpoint: http://collector:4318/v1/metrics OTEL_EXPORTER_OTLP_PROTOCOL: HttpProtobuf ``` Può anche configurare endpoint specifici per ciascun segnale: ``` 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/it/piattaforma/plugins/opentelemetry.md?ask=&goal= ``` `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.