OpenTelemetry Observability — Content Types & Use Cases
Package:
@vicacha-devs/strapi-plugin-opentelemetry· Plugin ID:opentelemetry
1. Content-Type Entities, Locations & Schemas (strapi.documents)
Section titled “1. Content-Type Entities, Locations & Schemas (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.
Where to Find Content-Type Entities in Strapi v5
Section titled “Where to Find Content-Type Entities in 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.
This plugin operates dynamically across existing Strapi api::* and plugin::* Content-Type entities without creating separate collection tables.
Strapi v5 Content Manager Integration (/admin/content-manager)
Section titled “Strapi v5 Content Manager Integration (/admin/content-manager)”Content Manager Sidebar Group:
No Content Manager panel; instruments the Document Service calls that Content Manager actions trigger
Content Manager Entities & Components
Section titled “Content Manager Entities & Components”- 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
Why This Plugin Creates & Integrates Content Manager Entities
Section titled “Why This Plugin Creates & Integrates Content Manager Entities”@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.
How to Use in Strapi Content Manager (Step-by-Step)
Section titled “How to Use in Strapi Content Manager (Step-by-Step)”- 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.
Content Manager & Plugin Workspace Synchronization
Section titled “Content Manager & Plugin Workspace Synchronization”Content Manager Use Cases & Editorial Workflows
Section titled “Content Manager Use Cases & Editorial Workflows”Content Manager Use Case 1 — Diagnosing Slow Publishes
Section titled “Content Manager Use Case 1 — Diagnosing Slow Publishes”- Why & What it is for: Identify which content type and plugin make publishing slow, without logging any entry content.
- How to use in 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. End-to-End Use Cases & Workflows
Section titled “3. End-to-End Use Cases & Workflows”Use Case 1 — Tracing Slow or Failing Requests Across Plugins
Section titled “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
Section titled “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
Section titled “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.