Observabilidad con OpenTelemetry — Guía de Desarrollo y Admin UI
1. Instalación y Dependencias
Sección titulada «1. Instalación y Dependencias»pnpm add @vicacha-devs/strapi-plugin-opentelemetry2. Configuración del Servidor (config/plugins.ts)
Sección titulada «2. Configuración del Servidor (config/plugins.ts)»Agregue la configuración del plugin en el archivo config/plugins.ts de su aplicación Strapi v5:
export default ({ env }: { env: (key: string, defaultValue?: string) => string }) => ({ "opentelemetry": { enabled: true, config: { serviceName: env("OTEL_SERVICE_NAME", "strapi-backend"), otlpEndpoint: env("OTEL_EXPORTER_OTLP_ENDPOINT", ""), sampleRate: 1.0, }, },});3. Recorrido por la Interfaz de Administración (Strapi v5 Admin UI)
Sección titulada «3. Recorrido por la Interfaz de Administración (Strapi v5 Admin UI)»Una vez habilitado, el plugin registra su espacio de trabajo y ajustes dentro del panel de administración de Strapi v5 utilizando Strapi Design System v2:
4. Entidades Content-Type, Ubicación y Esquemas (strapi.documents)
Sección titulada «4. 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.
5. Casos de Uso y Flujos de Trabajo
Sección titulada «5. 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.
6. Endpoints REST API (content-api y admin)
Sección titulada «6. Endpoints REST API (content-api y admin)»| Método | Ruta del Endpoint | Ámbito | Controlador | Autenticación |
|---|
7. Uso Programático en el Servidor (strapi.plugin y strapi.documents)
Sección titulada «7. Uso Programático en el Servidor (strapi.plugin y strapi.documents)»// Registered services on plugin "opentelemetry": "service"const pluginService = strapi.plugin("opentelemetry")?.service("service");
// Retrieving plugin settings via Strapi plugin storeconst store = strapi.store({ type: "plugin", name: "opentelemetry" });const settings = await store.get({ key: "settings" });8. Solución de Problemas y Verificación
Sección titulada «8. Solución de Problemas y Verificación»- Cambios no visibles en el panel Admin: Ejecute
pnpm strapi builddespués de editarconfig/plugins.ts. - Aislamiento de dependencias peer: Mantenga
hoistPattern: ["*", "!@strapi/*"]enpnpm-workspace.yamlpara evitar colisiones de contexto en React. - Verificación estricta de TypeScript: Ejecute
pnpm checkpara validaradmin/tsconfig.jsonyserver/tsconfig.json.