Jannes Stubbemann
362c30ccdc
## Thinking Path > - Paperclip orchestrates AI agents for zero-human companies > - Production self-hosters increasingly expect telemetry out of the box — Jaeger, Tempo, Honeycomb, Datadog, Grafana Cloud, Dynatrace all speak OTLP > - Today there is no OpenTelemetry bootstrap in the server, so operators who want traces have to patch their fork or run a sidecar that captures only HTTP-level info > - An opt-in bootstrap that costs nothing when disabled is the minimum-viable surface for this audience > - The OpenTelemetry packages are heavyweight enough that we don't want them in the default dependency graph — they should load only when the operator configures an OTLP endpoint > - This pull request adds a self-contained `server/src/instrumentation.ts` that dynamically imports the OTel SDK and starts it when `OTEL_EXPORTER_OTLP_ENDPOINT` is set, and is a complete no-op otherwise ## Linked Issues or Issue Description No existing issue covers this directly — feature-gap description following the feature-request template: **Problem or motivation** Production self-hosters increasingly expect telemetry out of the box — Jaeger, Tempo, Honeycomb, Datadog, Grafana Cloud, Dynatrace all speak OTLP — but the server has no OpenTelemetry bootstrap. Operators who want traces today must patch their fork or run a sidecar that captures only HTTP-level information. **Proposed solution** An opt-in OTel bootstrap gated on `OTEL_EXPORTER_OTLP_ENDPOINT`, loaded via dynamic `import()` only when configured, so the heavyweight OTel packages stay out of the default dependency graph. **Alternatives considered** Related open PRs found during the duplicate-PR search approach observability differently: #4894 adds OTLP instrumentation to Paperclip core unconditionally, and #3752 proposes an observability plugin. Not duplicates — different layering: this PR keeps the default install dependency-free via opt-in dynamic import. ## What Changed - New `server/src/instrumentation.ts` — opt-in OpenTelemetry auto-instrumentation. Gated on `OTEL_EXPORTER_OTLP_ENDPOINT`. Respects the standard OTel env vars (`OTEL_SERVICE_NAME`, `OTEL_SERVICE_VERSION`, `OTEL_EXPORTER_OTLP_ENDPOINT`). Skips the fs/dns/net auto-instrumentations (too chatty). `sdk.start()` is wrapped in try/catch so a bad endpoint or missing native bindings doesn't crash the server. `process.once("SIGTERM" / "SIGINT", …)` for clean shutdown on the first signal only. OTel packages are loaded via dynamic `import()` so they are true optional runtime dependencies — no entries in `package.json`, no lockfile churn. - `server/src/index.ts` — import `./instrumentation.js` as the very first statement so auto-instrumentation can patch `http` / `express` / `pg` before they are evaluated by downstream modules. ## Verification - `OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317 pnpm start` after `pnpm install @opentelemetry/{sdk-node,auto-instrumentations-node,exporter-trace-otlp-grpc,resources,semantic-conventions}` in `server/` — traces show up in the configured collector; HTTP, Express, and Postgres spans are populated. - `OTEL_EXPORTER_OTLP_ENDPOINT` unset — server starts with no OTel-shaped output in logs, no behavior change. - `OTEL_EXPORTER_OTLP_ENDPOINT=…` set but packages not installed — single `console.warn` at startup telling the operator which packages to install. ## Risks Low. No behavior change unless the env var is set. The bootstrap never throws into the caller; every failure path ends in `console.warn` / `console.error` and falls through to non-traced operation. ## Model Used Claude Opus 4.6 (1M context), extended thinking mode. ## Checklist - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] Thinking path traces from project context to this change - [x] Model used specified - [x] Tests run locally and pass - [x] CI green - [x] Greptile review addressed --------- Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
77 lines
2.7 KiB
Markdown
77 lines
2.7 KiB
Markdown
# Observability
|
|
|
|
Paperclip ships with **opt-in** OpenTelemetry auto-instrumentation for the
|
|
server process. When activated it produces **traces only** — no metrics and no
|
|
logs are exported by this integration. The OTel packages are *optional peer
|
|
dependencies*: they are not in the default lockfile and are loaded dynamically
|
|
only when an operator turns the feature on.
|
|
|
|
When `OTEL_EXPORTER_OTLP_ENDPOINT` is unset, none of the `@opentelemetry/*`
|
|
packages are imported and there is zero runtime overhead.
|
|
|
|
## Enabling tracing
|
|
|
|
### 1. Install the OTel peer dependencies
|
|
|
|
Install the SDK, the auto-instrumentations bundle, the resources/semconv
|
|
helpers, and **one** exporter matching your chosen OTLP protocol.
|
|
|
|
Common to every protocol:
|
|
|
|
```bash
|
|
pnpm add \
|
|
@opentelemetry/sdk-node \
|
|
@opentelemetry/auto-instrumentations-node \
|
|
@opentelemetry/resources \
|
|
@opentelemetry/semantic-conventions
|
|
```
|
|
|
|
Then add the exporter for the protocol you intend to use:
|
|
|
|
| `OTEL_EXPORTER_OTLP_PROTOCOL` | Exporter package |
|
|
| ----------------------------- | --------------------------------------------- |
|
|
| `grpc` (default if unset) | `@opentelemetry/exporter-trace-otlp-grpc` |
|
|
| `http/protobuf` | `@opentelemetry/exporter-trace-otlp-proto` |
|
|
| `http/json` | `@opentelemetry/exporter-trace-otlp-http` |
|
|
|
|
For example, for the default gRPC path:
|
|
|
|
```bash
|
|
pnpm add @opentelemetry/exporter-trace-otlp-grpc
|
|
```
|
|
|
|
### 2. Set the environment
|
|
|
|
Minimal setup:
|
|
|
|
```bash
|
|
# Required — turns the feature on. Point at your collector.
|
|
# For grpc this is the gRPC target (typically port 4317). For the HTTP
|
|
# protocols give the collector's BASE URL (typically port 4318) — the
|
|
# exporter appends /v1/traces itself.
|
|
export OTEL_EXPORTER_OTLP_ENDPOINT="http://otel-collector:4317"
|
|
|
|
# Optional — protocol. Defaults to grpc when unset.
|
|
# Valid values: grpc | http/protobuf | http/json
|
|
export OTEL_EXPORTER_OTLP_PROTOCOL="grpc"
|
|
|
|
# Optional — service identity attached to every span.
|
|
export OTEL_SERVICE_NAME="paperclip"
|
|
export OTEL_SERVICE_VERSION="2026.5.0"
|
|
```
|
|
|
|
If `OTEL_EXPORTER_OTLP_PROTOCOL` is set to an unrecognized value, Paperclip
|
|
logs a single warning and falls back to gRPC.
|
|
|
|
If `OTEL_EXPORTER_OTLP_ENDPOINT` is set but the OTel packages are not
|
|
installed, the server logs a single diagnostic line on boot and continues
|
|
without tracing — your server stays up.
|
|
|
|
## Scope
|
|
|
|
This integration emits **traces only**. Metrics and log exporters are out of
|
|
scope and intentionally not configured here. Auto-instrumentations for
|
|
`fs`, `dns`, and `net` are disabled by default because they are too chatty
|
|
for this workload; everything else from
|
|
`@opentelemetry/auto-instrumentations-node` is on (HTTP, Express, PG, etc.).
|