@vicacha-devs/strapi-plugin-opentelemetry 0.0.0-stage → 1.0.1

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vicacha Devs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,111 @@
-# Temporary Holding Version
+# `@vicacha-devs/strapi-plugin-opentelemetry`
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Vendor-neutral **OpenTelemetry** error tracking and performance monitoring (APM) plugin for **Strapi v5**.
+
+Instruments Node.js, HTTP/Koa requests, PostgreSQL/SQLite queries, Strapi v5 Document Service operations, and caught plugin errors (`strapi.log.error`), exporting traces and metrics over **OTLP/HTTP** to **SigNoz**, **Grafana Tempo / Alloy**, **Sentry OTLP**, **Datadog**, **Jaeger**, or any OpenTelemetry Collector.
+
+## Key Features
+
+- **Automatic Node.js & Database Instrumentation**: Traces incoming/outgoing HTTP (`http`, `undici`) and database calls (`pg`, etc.) via `@opentelemetry/auto-instrumentations-node` (with noisy `fs` instrumentation disabled).
+- **HTTP Request Tracking & APM Metrics**: Records `http.server.request.duration` histograms, `http.server.errors` counters, `http.route`, `http.response.status_code`, and authenticated `enduser.id`.
+- **Strapi v5 Document Service Tracing**: Wraps `strapi.documents.use(...)` in child spans (`strapi.document.<action> <uid>`) with `strapi.document.uid`, `strapi.document.action`, and `strapi.plugin` attributes.
+- **Per-Plugin Failure Attribution**: Automatically extracts `strapi.plugin` from `plugin::<name>.<model>` UIDs and plugin route paths (e.g., `/api/bookings/...` -> `bookings`).
+- **Caught Plugin Error Capture**: Hooks `strapi.log.error` so errors caught and logged inside plugins, email lifecycles, or background jobs are recorded as `exception` span events and counted in `strapi.log.errors`.
+- **Log-Trace Correlation**: Logs `trace_id`, `span_id`, `method`, `path`, and `plugin` on unhandled request errors.
+- **Built-In Secret & PII Redaction**: Scrubs `Bearer`/`Basic` tokens, URL credentials (`user:pass@`), sensitive query parameters (`token`, `api_key`, `secret`, `password`, etc.), and email addresses from error messages, stack traces, and outgoing `url.full`/`http.url`/`url.query` span attributes before export.
+- **Graceful Shutdown**: Flushes buffered spans and metrics in Strapi's `destroy()` lifecycle hook.
+
+## Installation & Configuration
+
+Add `@vicacha-devs/strapi-plugin-opentelemetry` to your Strapi v5 project and configure it in `config/plugins.ts`:
+
+```ts
+export default ({ env }) => ({
+  opentelemetry: {
+    enabled: env.bool("OTEL_ENABLED", true),
+    config: {
+      serviceName: env("OTEL_SERVICE_NAME", "strapi-backend"),
+      serviceVersion: env("npm_package_version", "1.0.0"),
+      environment: env("NODE_ENV", "development"),
+      otlpEndpoint: env("OTEL_EXPORTER_OTLP_ENDPOINT", ""),
+      sampleRate: Number(env("OTEL_TRACES_SAMPLE_RATE", "1.0")),
+      ignorePaths: ["/_health", "/favicon.ico"],
+      captureDocumentService: true,
+      consoleExporter: env.bool("OTEL_CONSOLE_EXPORTER", false),
+    },
+  },
+});
+```
+
+## Configuration Reference
+
+All options are validated at Strapi boot time by `validateOtelConfig`. Standard OpenTelemetry environment variables (`OTEL_EXPORTER_OTLP_ENDPOINT`, `OTEL_SERVICE_NAME`, `OTEL_EXPORTER_OTLP_HEADERS`) are automatically merged.
+
+| Option | Env Variable | Type | Default | Description |
+| :--- | :--- | :--- | :--- | :--- |
+| `enabled` | `OTEL_ENABLED` | `boolean` | `true` | Enable or disable SDK, middleware, and hooks |
+| `serviceName` | `OTEL_SERVICE_NAME` | `string` | `"strapi"` | Service name reported in `service.name` |
+| `serviceVersion` | — | `string` | `"1.0.0"` | Service version reported in `service.version` |
+| `environment` | `NODE_ENV` | `string` | `process.env.NODE_ENV \|\| "development"` | Reported in `deployment.environment.name` |
+| `otlpEndpoint` | `OTEL_EXPORTER_OTLP_ENDPOINT` | `string` | `""` | Base OTLP/HTTP URL (exports to `/v1/traces` and `/v1/metrics`) |
+| `otlpHeaders` | `OTEL_EXPORTER_OTLP_HEADERS` | `Record<string, string>` | `{}` | Auth/tenant headers (env format: `k1=v1,k2=v2`) |
+| `sampleRate` | `OTEL_TRACES_SAMPLE_RATE` | `number` (`0..1`) | `1.0` | Root trace sampling ratio wrapped in `ParentBasedSampler` |
+| `ignorePaths` | — | `string[]` | `["/_health", "/favicon.ico"]` | URL path prefixes excluded from HTTP tracing/metrics |
+| `captureDocumentService` | — | `boolean` | `true` | Wrap `strapi.documents.use(...)` calls in child spans |
+| `consoleExporter` | `OTEL_CONSOLE_EXPORTER` | `boolean` | `false` | Export spans to stdout when `otlpEndpoint` is empty |
+| `metricExportIntervalMs` | — | `number` (`>= 1000`) | `60000` | Interval in ms for `PeriodicExportingMetricReader` |
+
+## Telemetry Emitted
+
+### Span Attributes
+- **HTTP Requests**: `http.request.method`, `url.path`, `http.route`, `http.response.status_code`, `strapi.plugin` (when matched), `enduser.id` (when authenticated).
+- **Document Service**: `strapi.document.uid`, `strapi.document.action`, `strapi.plugin` (for `plugin::*` UIDs).
+- **Errors**: `exception` span event with sanitized `Error` + `SpanStatusCode.ERROR` on unhandled exceptions, HTTP `>= 500` responses, and `strapi.log.error(...)` calls.
+
+### Metrics
+- `http.server.request.duration` (Histogram, `ms`) — Request latency by method, route, status/error type, and `strapi.plugin`.
+- `http.server.errors` (Counter) — Count of `>= 500` and unhandled HTTP errors.
+- `strapi.log.errors` (Counter) — Count of errors logged via `strapi.log.error`.
+
+## Security & Privacy
+
+- **Zero body/header logging**: Request/response payloads, `Authorization`, `Cookie`, and user emails/names are never attached to spans.
+- **Automatic redaction**: `SanitizingSpanExporter`, `sanitizeError`, and `sanitizeTelemetryText` scrub `Bearer`/`Basic` tokens, URL credentials, sensitive query keys (`token`, `access_token`, `api_key`, `key`, `secret`, `password`, `auth`, `signature`, `code`), and email addresses before telemetry leaves the process.
+- **Production checklist**:
+  - Use `https://` for `OTEL_EXPORTER_OTLP_ENDPOINT` outside localhost/private VPCs.
+  - Keep `OTEL_CONSOLE_EXPORTER=false` in production.
+  - Store `OTEL_EXPORTER_OTLP_HEADERS` in your secrets manager.
+
+## Collector Examples
+
+- **SigNoz / Grafana Alloy / Local OTel Collector:**
+  ```env
+  OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
+  ```
+- **Sentry OTLP Ingest:**
+  ```env
+  OTEL_EXPORTER_OTLP_ENDPOINT=https://o0.ingest.sentry.io/api/<project-id>/integration/otlp
+  OTEL_EXPORTER_OTLP_HEADERS="x-sentry-auth=sentry sentry_key=<public-key>"
+  ```
+- **Local Development (stdout only):**
+  ```env
+  OTEL_CONSOLE_EXPORTER=true
+  ```
+
+## Custom Instrumentation
+
+Use `@opentelemetry/api` anywhere in your Strapi services, controllers, or plugins—spans will automatically nest under the active request trace:
+
+```ts
+import { trace } from "@opentelemetry/api";
+
+const tracer = trace.getTracer("my-plugin");
+
+await tracer.startActiveSpan("bookings.syncCalendar", async (span) => {
+  try {
+    // your work
+  } finally {
+    span.end();
+  }
+});
+```

package/dist/admin/index.d.ts

@@ -0,0 +1,7 @@
+interface StrapiAdminApp {
+    registerPlugin: (plugin: Record<string, unknown>) => void;
+}
+declare const _default: {
+    register(app: StrapiAdminApp): void;
+};
+export default _default;

package/dist/admin/index.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperties(exports, { __esModule: { value: true }, [Symbol.toStringTag]: { value: "Module" } });
+const PLUGIN_ID = "opentelemetry";
+const index = {
+  register(app) {
+    app.registerPlugin({
+      id: PLUGIN_ID,
+      name: PLUGIN_ID
+    });
+  }
+};
+exports.default = index;

package/dist/admin/index.mjs

@@ -0,0 +1,12 @@
+const PLUGIN_ID = "opentelemetry";
+const index = {
+  register(app) {
+    app.registerPlugin({
+      id: PLUGIN_ID,
+      name: PLUGIN_ID
+    });
+  }
+};
+export {
+  index as default
+};

package/dist/admin/pluginId.d.ts

@@ -0,0 +1 @@
+export declare const PLUGIN_ID = "opentelemetry";

package/dist/server/config.d.ts

@@ -0,0 +1,26 @@
+export interface OtelPluginConfig {
+    enabled: boolean;
+    serviceName: string;
+    serviceVersion: string;
+    environment: string;
+    otlpEndpoint: string;
+    otlpHeaders: Record<string, string>;
+    sampleRate: number;
+    ignorePaths: string[];
+    captureDocumentService: boolean;
+    consoleExporter: boolean;
+    metricExportIntervalMs: number;
+}
+export declare const defaultConfig: OtelPluginConfig;
+/**
+ * Parses an OTLP header string (`key1=val1,key2=val2`) into a plain object.
+ */
+export declare function parseOtlpHeaders(raw: string | undefined): Record<string, string>;
+/**
+ * Merges plugin config with standard `OTEL_*` environment variables.
+ */
+export declare function resolveOtelConfig(rawConfig?: Partial<OtelPluginConfig>): OtelPluginConfig;
+/**
+ * Validates the OpenTelemetry plugin configuration at Strapi boot time.
+ */
+export declare function validateOtelConfig(pluginConfig: unknown): void;

package/dist/server/documents.d.ts

@@ -0,0 +1,12 @@
+import { OtelPluginConfig } from './config';
+export interface DocumentServiceContext {
+    uid: string;
+    action: string;
+}
+export interface StrapiDocumentsLike {
+    use: (middleware: (context: DocumentServiceContext, next: () => Promise<unknown>) => Promise<unknown>) => void;
+}
+/**
+ * Instruments Strapi v5 Document Service operations with child spans and error recording.
+ */
+export declare function registerDocumentServiceInstrumentation(documents: StrapiDocumentsLike | undefined, config: OtelPluginConfig): void;

package/dist/server/index.d.ts

@@ -0,0 +1,22 @@
+import { Core } from '@strapi/strapi';
+import { validateOtelConfig, OtelPluginConfig } from './config';
+import { KoaLikeContext } from './middleware';
+declare const _default: {
+    register({ strapi }: {
+        strapi: Core.Strapi;
+    }): void;
+    bootstrap({ strapi }: {
+        strapi: Core.Strapi;
+    }): void;
+    destroy(): Promise<void>;
+    config: {
+        default: OtelPluginConfig;
+        validator: typeof validateOtelConfig;
+    };
+    middlewares: {
+        tracker: (_config: unknown, { strapi }: {
+            strapi: Core.Strapi;
+        }) => (ctx: KoaLikeContext, next: () => Promise<void>) => Promise<void>;
+    };
+};
+export default _default;