Observabilidad con OpenTelemetry (@vicacha-devs/strapi-plugin-opentelemetry)
Package:
@vicacha-devs/strapi-plugin-opentelemetry· Plugin ID:opentelemetry· Category:Observability· Version:1.0.1· Routes:0
Seguimiento de errores y APM con OpenTelemetry sin dependencia de proveedor: trazas y métricas OTLP/HTTP, spans hijos del Document Service, captura de strapi.log.error, atribución por plugin y redacción automática de secretos y datos personales.
pnpm add @vicacha-devs/strapi-plugin-opentelemetry1. Características Principales y Arquitectura
Sección titulada «1. Características Principales y Arquitectura»- Explorar Entidades Content-Type y Casos de Uso (con Diagramas Interactivos)
- Explorar la Guía de Desarrollo y Admin UI
2. Entidades Content-Type, Ubicación y Esquemas (strapi.documents)
Sección titulada «2. Entidades Content-Type, Ubicación y Esquemas (strapi.documents)»Registers no Content-Types, routes, or admin pages. When enabled, the server register() lifecycle validates the config, starts the OpenTelemetry Node SDK (OTLP/HTTP traces and metrics plus auto-instrumentations), hooks strapi.log.error, adds a request middleware (HTTP spans, the http.server.request.duration histogram, and the http.server.errors counter), and, when captureDocumentService is true, wraps Document Service calls in child spans named strapi.document.<action> <uid>. bootstrap() logs the active exporter and destroy() flushes buffered spans and metrics. All exported error text passes through built-in secret and PII redaction.
Dónde Encontrar las Entidades Content-Type en Strapi v5
Sección titulada «Dónde Encontrar las Entidades Content-Type en Strapi v5»- Strapi Boot Log:
[opentelemetry] Active for service ...is logged frombootstrap()with the service name and the exporter target (otlpEndpoint,console, orno-exporter). - Your OTLP Backend: traces and metrics arrive at
<otlpEndpoint>/v1/tracesand<otlpEndpoint>/v1/metricsin SigNoz, Grafana, Sentry OTLP ingest, or any OTLP/HTTP collector. - Strapi Config:
config/plugins.ts->opentelemetry.config, validated at boot byvalidateOtelConfig. - No Admin UI or Content-Types: this plugin creates no entities, routes, settings page, or database tables.
Este plugin opera dinámicamente sobre las entidades Content-Type existentes de Strapi (api::* y plugin::*).
Integración con el Content Manager de Strapi v5 (/admin/content-manager)
Sección titulada «Integración con el Content Manager de Strapi v5 (/admin/content-manager)»Grupo en la Barra Lateral del Content Manager:
No Content Manager panel; instruments the Document Service calls that Content Manager actions trigger
Entidades y Componentes en el Content Manager
Sección titulada «Entidades y Componentes en el Content Manager»- Document Service calls (
strapi.documents(...)) made when editors create, update, publish, or delete entries in/admin/content-manager, recorded asstrapi.document.<action> <uid>child spans - No Content-Type, route, or database table is created by this plugin
Por Qué Este Plugin Crea e Integra Entidades en el Content Manager
Sección titulada «Por Qué Este Plugin Crea e Integra Entidades en el Content Manager»@vicacha-devs/strapi-plugin-opentelemetry adds no Content Manager UI. Every create, update, publish, or delete an editor performs becomes a traced Document Service operation, so slow or failing saves can be tied to a specific content type and plugin in your observability backend.
- Per-Content-Type Visibility: spans carry
strapi.document.uid,strapi.document.action, andstrapi.plugin(forplugin::*UIDs). - Opt-Out per Environment: set
captureDocumentService: falseto stop wrapping Document Service calls without disabling HTTP tracing. - Safe by Default: payloads and user identity beyond
enduser.idare never attached to spans, and error text is redacted before export.
Cómo Usarlo en el Content Manager de Strapi (Paso a Paso)
Sección titulada «Cómo Usarlo en el Content Manager de Strapi (Paso a Paso)»- Enable the Plugin: add
opentelemetrytoconfig/plugins.tsand setOTEL_EXPORTER_OTLP_ENDPOINT(orOTEL_CONSOLE_EXPORTER=truelocally). - Work Normally in Content Manager: save or publish entries in
/admin/content-manager. - Inspect the Traces: search your backend for
strapi.document.update(orcreate,publish,delete) spans filtered bystrapi.document.uid.
Sincronización entre el Content Manager y el Espacio del Plugin
Sección titulada «Sincronización entre el Content Manager y el Espacio del Plugin»Casos de Uso en el Content Manager y Flujos Editoriales
Sección titulada «Casos de Uso en el Content Manager y Flujos Editoriales»Content Manager Use Case 1 — Diagnosing Slow Publishes
Sección titulada «Content Manager Use Case 1 — Diagnosing Slow Publishes»- Para qué sirve y por qué usarlo: Identify which content type and plugin make publishing slow, without logging any entry content.
- Cómo ejecutarlo en el Content Manager: Publish an entry in
/admin/content-manager, then find thestrapi.document.publish <uid>span under the request trace and compare its duration with other content types.
3. Casos de Uso y Flujos de Trabajo
Sección titulada «3. Casos de Uso y Flujos de Trabajo»Use Case 1 — Tracing Slow or Failing Requests Across Plugins
Sección titulada «Use Case 1 — Tracing Slow or Failing Requests Across Plugins»- What it is for: Find which plugin makes an endpoint slow or failing, using the
strapi.pluginattribute derived fromplugin::<name>.<model>UIDs and plugin route paths (for example/api/bookings/...->bookings). - How it works: Point
otlpEndpointat your collector; each request produces an HTTP span withhttp.route,http.response.status_code, andstrapi.plugin, andhttp.server.request.durationis recorded by method, route, and status.
Use Case 2 — Capturing Caught Errors from Plugins and Background Jobs
Sección titulada «Use Case 2 — Capturing Caught Errors from Plugins and Background Jobs»- What it is for: Surface errors that plugins, email lifecycles, or background jobs catch and only log, which would otherwise never reach an error tracker.
- How it works: The plugin hooks
strapi.log.error, records each call as anexceptionspan event, and counts it instrapi.log.errors; unhandled request errors also logtrace_id,span_id,method,path, andpluginfor log-trace correlation.
Use Case 3 — Shipping Telemetry Without Leaking Secrets or PII
Sección titulada «Use Case 3 — Shipping Telemetry Without Leaking Secrets or PII»- What it is for: Send traces to a third-party backend while keeping credentials and personal data out of them.
- How it works: Request bodies,
Authorization,Cookie, and user emails or names are never attached to spans. Error text is redacted forBearer/Basictokens, URL credentials, sensitive query parameters, and email addresses, and is length-bounded before redaction so pathological input cannot stall the sanitizer.
4. Endpoints REST API (content-api y admin)
Sección titulada «4. Endpoints REST API (content-api y admin)»| Método | Ruta del Endpoint | Ámbito | Controlador | Autenticación |
|---|