Skip to content

OpenTelemetry Observability — Developer Guide & Admin UI

Terminal window
pnpm add @vicacha-devs/strapi-plugin-opentelemetry

2. 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:

config/plugins.ts
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,
},
},
});

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 from bootstrap() with the service name and the exporter target (otlpEndpoint, console, or no-exporter).
  • Your OTLP Backend: traces and metrics arrive at <otlpEndpoint>/v1/traces and <otlpEndpoint>/v1/metrics in SigNoz, Grafana, Sentry OTLP ingest, or any OTLP/HTTP collector.
  • Strapi Config: config/plugins.ts -> opentelemetry.config, validated at boot by validateOtelConfig.
  • 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

  • Document Service calls (strapi.documents(...)) made when editors create, update, publish, or delete entries in /admin/content-manager, recorded as strapi.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, and strapi.plugin (for plugin::* UIDs).
  • Opt-Out per Environment: set captureDocumentService: false to stop wrapping Document Service calls without disabling HTTP tracing.
  • Safe by Default: payloads and user identity beyond enduser.id are 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)”
  1. Enable the Plugin: add opentelemetry to config/plugins.ts and set OTEL_EXPORTER_OTLP_ENDPOINT (or OTEL_CONSOLE_EXPORTER=true locally).
  2. Work Normally in Content Manager: save or publish entries in /admin/content-manager.
  3. Inspect the Traces: search your backend for strapi.document.update (or create, publish, delete) spans filtered by strapi.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 the strapi.document.publish <uid> span under the request trace and compare its duration with other content types.

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.plugin attribute derived from plugin::<name>.<model> UIDs and plugin route paths (for example /api/bookings/... -> bookings).
  • How it works: Point otlpEndpoint at your collector; each request produces an HTTP span with http.route, http.response.status_code, and strapi.plugin, and http.server.request.duration is 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 an exception span event, and counts it in strapi.log.errors; unhandled request errors also log trace_id, span_id, method, path, and plugin for 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 for Bearer/Basic tokens, 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 store
const store = strapi.store({ type: "plugin", name: "opentelemetry" });
const settings = await store.get({ key: "settings" });
  • Admin panel changes not visible: Run pnpm strapi build after modifying config/plugins.ts.
  • Peer dependency isolation: Keep hoistPattern: ["*", "!@strapi/*"] in pnpm-workspace.yaml so @strapi/* contexts are never duplicated.
  • TypeScript type-checking: Validate both admin/tsconfig.json and server/tsconfig.json via pnpm --filter <pkg> test:ts.