OpenTelemetry Observability — Developer Guide & Admin UI
1. Installation & Peer Setup
Section titled “1. Installation & Peer Setup”pnpm add @vicacha-devs/strapi-plugin-opentelemetry2. Server Configuration (config/plugins.ts)
Section titled “2. Server Configuration (config/plugins.ts)”Add the plugin configuration to your Strapi v5 config/plugins.ts file:
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. Strapi v5 Admin UI Tour
Section titled “3. Strapi v5 Admin UI Tour”Once enabled, the plugin registers its workspace and settings inside the Strapi v5 Admin panel using Strapi Design System v2 components:
4. Content-Type Entities, Locations & Schemas (strapi.documents)
Section titled “4. 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.
5. End-to-End Use Cases & Workflows
Section titled “5. 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.
6. REST API Endpoints (content-api & admin)
Section titled “6. REST API Endpoints (content-api & admin)”| Method | Endpoint Path | Scope | Controller Handler | Auth |
|---|
7. Programmatic Server Usage (strapi.plugin & strapi.documents)
Section titled “7. Programmatic Server Usage (strapi.plugin & 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. Troubleshooting & Verification
Section titled “8. Troubleshooting & Verification”- Admin panel changes not visible: Run
pnpm strapi buildafter modifyingconfig/plugins.ts. - Peer dependency isolation: Keep
hoistPattern: ["*", "!@strapi/*"]inpnpm-workspace.yamlso@strapi/*contexts are never duplicated. - TypeScript type-checking: Validate both
admin/tsconfig.jsonandserver/tsconfig.jsonviapnpm --filter <pkg> test:ts.