{"locator":"npm:@open-mercato/telemetry","path":"@open-mercato/telemetry","npm":"@open-mercato/telemetry","github":null,"repoPath":"open-mercato/open-mercato#main/packages/telemetry","kind":"module","type":"official","enterprise":false,"title":"Telemetry","summary":"Exports traces, metrics, logs and errors over OTLP/HTTP. Off by default and not loaded until TELEMETRY_BACKEND is set.","whenToUse":"Use when you run an OpenTelemetry collector or a managed OTLP backend and want app traces and errors there.","whenNotToUse":null,"category":"storage-infrastructure","tags":["opentelemetry","tracing","metrics"],"providers":[],"moduleIds":["telemetry"],"requires":[],"replaces":[],"slotConflicts":[],"renamedFrom":[],"supersededBy":null,"alternatives":[],"status":"active","listed":true,"featured":false,"license":{"spdx":"MIT","kind":"osi","mismatch":false},"version":{"latest":"0.9.0","preview":null,"publishedAt":"2026-10-09","integrity":"sha512-VI9ry8eMjKFwHRCPA4V1z9TJtkfjz4HJR4M8V5s2NKBFsvP9t5rbUTdrcY5z/aifoYUeLdpCzX8ZHr2cHdrukA==","installableFrom":"2026-10-09","gitRef":null,"recommended":{"0.9":null,"0.8":null,"next":null}},"identity":{"builtFrom":"verified","claimed":false,"source":"npm"},"compat":{"builtFor":{"range":null,"kind":"missing","lines":[]},"lines":{},"verifiedOn":[],"inPresets":["0.9","next"],"ships":{"0.9":"0.9.0","next":"0.10.1-develop.7701.1.87b1ad4224"}},"anatomy":{"version":"0.9.0","coverage":"partial","counts":{"entities":0,"tables":0,"migrations":0,"routes":1,"publicRoutes":0,"aclFeatures":0,"eventsEmitted":0,"eventsConsumed":0,"backendPages":0,"frontendPages":0,"widgets":0,"workers":0,"cli":0,"aiTools":0,"aiAgents":0,"extends":0},"lists":{"aclFeatures":[],"eventsEmitted":[],"eventsConsumed":[],"env":["OM_TEST_MODE","OM_TEST_BROWSER_TELEMETRY_MODE","OTEL_SERVICE_NAME","OTEL_RESOURCE_ATTRIBUTES","TELEMETRY_BROWSER_ENABLED","TELEMETRY_BROWSER_SERVICE_NAME","TELEMETRY_BROWSER_SAMPLING_RATIO","OTEL_EXPORTER_OTLP_TRACES_ENDPOINT","OTEL_EXPORTER_OTLP_ENDPOINT","OTEL_EXPORTER_OTLP_HEADERS","TELEMETRY_BACKEND","TELEMETRY_SAMPLING_RATIO","TELEMETRY_TRUST_INBOUND_TRACE"],"hosts":[],"tables":[],"publicRoutes":[],"credentials":[]},"callout":"ADDS 1 ROUTE (0 PUBLIC)","diff":{"from":"0.8.0","added":{"tables":0,"routes":1,"publicRoutes":0,"aclFeatures":0,"env":["OM_TEST_MODE","OM_TEST_BROWSER_TELEMETRY_MODE","OTEL_SERVICE_NAME","OTEL_RESOURCE_ATTRIBUTES","TELEMETRY_BROWSER_ENABLED","TELEMETRY_BROWSER_SERVICE_NAME","TELEMETRY_BROWSER_SAMPLING_RATIO","OTEL_EXPORTER_OTLP_TRACES_ENDPOINT","OTEL_EXPORTER_OTLP_ENDPOINT","OTEL_EXPORTER_OTLP_HEADERS","TELEMETRY_BACKEND","TELEMETRY_SAMPLING_RATIO","TELEMETRY_TRUST_INBOUND_TRACE"],"hosts":[]},"removed":{"tables":0,"routes":0,"aclFeatures":0}}},"signals":{"receipt":{"0.9":"untested","0.8":"untested","next":"untested"},"fit":{"0.9":"ok","0.8":"ok","next":"unknown"},"anatomy":"partial","supplyChain":{"status":"ok","reasons":[]},"hygiene":{"status":"ok","failing":[]},"maintenance":{"status":"current","lastRelease":"2026-10-09","catchUpDays":null},"declaredVsObserved":{"status":"mismatch","notes":["No Open Mercato peer range; verified on no line."]}},"tier":"listed","quality":null,"agentPolicy":{"0.9":{"decision":"ask","reasons":[{"code":"NOT_VERIFIED","text":"Not yet tested in a new app on 0.9."},{"code":"IN_PRESET","text":"Nothing to install: a new app already registers telemetry in src/modules.ts."}]},"0.8":{"decision":"ask","reasons":[{"code":"NOT_VERIFIED","text":"Not yet tested in a new app on 0.8."}],"consentText":"Install @open-mercato/telemetry@0.8.0"},"next":{"decision":"ask","reasons":[{"code":"NOT_VERIFIED","text":"Not yet tested in a new app on next."},{"code":"IN_PRESET","text":"Nothing to install: a new app already registers telemetry in src/modules.ts."}]}},"install":{"cli":"yarn mercato module add @open-mercato/telemetry@0.9.0","cmm":"npx create-mercato-module install @open-mercato/telemetry@0.9.0","needsAllowThirdParty":false,"moduleFlag":null},"stats":{"downloads30d":38960,"stars":null},"sigil":{"glyph":"0100000","phase":17,"publicRoutes":false},"links":{"page":"https://modules.openmercato.com/m/@open-mercato/telemetry","md":"https://modules.openmercato.com/m/@open-mercato/telemetry.md","json":"https://modules.openmercato.com/m/@open-mercato/telemetry.json","facts":"https://modules.openmercato.com/m/@open-mercato/telemetry/v/0.9.0/facts.json","npm":"https://www.npmjs.com/package/@open-mercato/telemetry","repo":"https://github.com/open-mercato/open-mercato","docs":"https://docs.openmercato.com/framework/runtime/telemetry"},"addedAt":"2026-10-23","updatedAt":"2026-10-29T13:11:45Z","_meta":{"com.openmercato.modules/installable":{"0.9":"0.9.0","0.8":"0.8.0","next":"0.9.0"}},"facts":{"factsVersion":1,"extractor":{"engine":"@open-mercato/cli@0.9.0 extractModuleFacts","factsContractVersion":2,"catalog":"om-modules rentgen 1","durationMs":35},"package":{"locator":"npm:@open-mercato/telemetry","name":"@open-mercato/telemetry","version":"0.9.0","integrity":"sha512-VI9ry8eMjKFwHRCPA4V1z9TJtkfjz4HJR4M8V5s2NKBFsvP9t5rbUTdrcY5z/aifoYUeLdpCzX8ZHr2cHdrukA==","source":"npm-tarball","gitRef":null},"gate":{"installable":true,"needsModuleFlag":false,"reason":null,"modules":[{"id":"telemetry","src":true,"dist":true}]},"kind":"module","license":{"value":"MIT","kind":"osi","mismatch":false,"sources":{"packageJson":"MIT","licenseFile":null,"moduleInfo":null,"integrationTs":null}},"omPeers":{},"dependencies":{"@open-mercato/shared":"0.9.0"},"agentsMd":true,"readmeExcerpt":"# @open-mercato/telemetry\n\nVendor-neutral tracing, metrics, log export, and error reporting for Open\nMercato, backed by a pluggable provider with OpenTelemetry (OTLP) as the default\ntransport.\n\nTelemetry is explicitly opt-in. The platform checks `TELEMETRY_BACKEND` from\nshared code before importing this package, so the telemetry runtime is not\nevaluated when the variable is unset, `noop`, or unknown. OpenTelemetry packages\nare optional dependencies and are dynamically imported only for an OTLP backend.\nPackage managers may still install optional dependencies; the guarantee is zero\ndisabled-path runtime loading, hook registration, or export traffic.\n\nSee [the telemetry spec](../../.ai/specs/2026-04-29-telemetry-and-otel.md).\n\n## Usage\n\nThe canonical application logger remains\n`@open-mercato/shared/lib/logger`. Telemetry extends it after successful\ninitialization with trace correlation and one remote sink; it does not create a\nsecond logger or local output path.\n\n```ts\nimport { createLogger } from '@open-mercato/shared/lib/logger'\nimport { withSpan, counter, reportError } from '@open-mercato/telemetry'\n\nconst log = createLogger('orders').child({ module: 'sales' })\nlog.info('Order placed', { orderId })\n\nawait withSpan('orders.checkout', async (span) => {\n  span.setAttribute('om.tenant_id', tenantId)\n  // pg/undici auto-spans nest here when OTLP is enabled\n})\n\ncounter('om.errors', 1, { module: 'orders' })\n\ntry {\n  // ...\n} catch (error) {\n  reportError(error, { module: 'orders' })\n  throw error\n}\n```\n\nUse `OM_LOG_LEVEL`, `OM_LOG_PRETTY`, and `OM_LOG_DESTINATION` for both the\nnormal local logger and telemetry-backed log export. Remote records follow the\nsame shared level gate as local records.\n\n## Enabling\n\nLeave `TELEMETRY_BACKEND` unset (or set it to `noop`) to keep telemetry off.\nUnknown values also resolve to off.\n\n```dotenv\nTELEMETRY_BACKEND=otlp\nTELEMETRY_SAMPLING_RATIO=0.1\nOTEL_EXPORTER_OTLP_ENDPOINT=https://<your-collector>:4318\nOTEL_EXPORTER_OTLP_HEADERS=<auth-header>=<key>\nOTEL_SERVICE_NAME=open-mercato\nOTEL_RESOURCE_ATTRIBUTES=deployment.environment=production\n```\n\n`otlp`, `signoz`, and `newrelic` select the same OTLP provider and differ\nonly by endpoint and headers. `console` is an explicit local span/metric\ndiagnostic backend.\n\n`TELEMETRY_TRUST_INBOUND_TRACE` defaults to false. In that mode both\n`traceparent` and `x-original-traceparent` from inbound/global carriers are\nignored because either header is caller-controlled. Set it to true only behind a\ntrusted upstream when global W3C continuation is required. The queue package's\ndedicated `metadata._trace` carrier does not require this flag. The richer\n`bullmq-otel` queue spans do use the process-global propagator, so they stay\ndisabled while this flag is false; async queues then use the dedicated carrier.\n\nCustom providers remain supported through `registerProvider()`. Because the\ndefault host guard deliberately imports telemetry only for built-in backend\nnames, a custom-provider bootstrap must import `@open-mercato/telemetry`,\nregister a provider whose `name` matches `TELEMETRY_BACKEND`, and call\n`initTelemetry()` directly. Unregistered names remain a hard no-op.\n\n## Browser RUM (client-side telemetry)\n\nServer traces can only prove where the time *isn't*: a page can render an API\nanswer in 50 ms yet leave the user waiting seconds on bundle download,\nhydration, or a click handler — all invisible to server spans. The\n`@open-mercato/telemetry/browser` entry closes that gap with the OpenTelemetry\nweb SDK: document-load and fetch spans from the backoffice.\n\nInteraction spans are deliberately **not** collected. The upstream\n`UserInteractionInstrumentation` patches `addEventListener` when it starts, but\nReact attaches a single delegated `click` listener to the root container during\nhydration — before this SDK boots from `useEffect` — so the patch would never see\na backoffice click. Booting earlier would put the SDK back on the critical path,\nwhich defeats the point; an instru","modules":[{"id":"telemetry","title":"Telemetry","description":null,"requires":[],"ejectable":null,"data":{"entities":[],"migrations":{"count":0,"first":null,"last":null},"customEntities":0},"http":{"routes":[{"method":"POST","path":"/api/telemetry/browser-traces","requireAuth":true,"requireFeatures":[],"hasOpenApi":true,"src":{"file":"src/modules/telemetry/api/browser-traces/route.ts","line":71}}],"legacyRouteFiles":0,"authResolved":1},"security":{"aclFeatures":[],"setupDefaultRoleFeatures":false},"events":{"emits":[],"subscribes":[]},"ui":{"backendPages":[],"frontendPages":[],"widgets":0,"extensionHosts":0},"background":{"workers":[],"cli":[]},"ai":{"tools":[],"agents":[]},"config":{"credentials":[],"env":[{"name":"OM_TEST_MODE","src":{"file":"src/browser/server.ts","line":96}},{"name":"OM_TEST_BROWSER_TELEMETRY_MODE","src":{"file":"src/browser/server.ts","line":97}},{"name":"OTEL_SERVICE_NAME","src":{"file":"src/browser/server.ts","line":103}},{"name":"OTEL_RESOURCE_ATTRIBUTES","src":{"file":"src/browser/server.ts","line":104}},{"name":"TELEMETRY_BROWSER_ENABLED","src":{"file":"src/browser/server.ts","line":124}},{"name":"TELEMETRY_BROWSER_SERVICE_NAME","src":{"file":"src/browser/server.ts","line":131}},{"name":"TELEMETRY_BROWSER_SAMPLING_RATIO","src":{"file":"src/browser/server.ts","line":138}},{"name":"OTEL_EXPORTER_OTLP_TRACES_ENDPOINT","src":{"file":"src/browser/server.ts","line":147}},{"name":"OTEL_EXPORTER_OTLP_ENDPOINT","src":{"file":"src/browser/server.ts","line":149}},{"name":"OTEL_EXPORTER_OTLP_HEADERS","src":{"file":"src/browser/server.ts","line":159}},{"name":"TELEMETRY_BACKEND","src":{"file":"src/env.ts","line":52}},{"name":"TELEMETRY_SAMPLING_RATIO","src":{"file":"src/env.ts","line":56}},{"name":"TELEMETRY_TRUST_INBOUND_TRACE","src":{"file":"src/env.ts","line":57}}]},"network":{"hosts":[],"undeclared":[]},"extends":[],"omImports":{"@open-mercato/shared":{"lib/auth/server":["AuthContext"],"lib/boolean":["parseBooleanWithDefault"],"lib/di/container":["createRequestContainer"],"lib/logger":["LoggerExtensionRecord","createLogger","registerLoggerExtension"],"lib/ratelimit/service":["RateLimiterService"],"lib/ratelimit/types":["RateLimitConfig"],"lib/telemetry/error-code":["groupableCode"],"lib/telemetry/runtime":["TelemetryRuntime","isTelemetryBackendEnabled","registerTelemetryRuntime"],"modules/registry":["ModuleInfo"]}},"collisionKeys":{"moduleId":"telemetry","tables":[],"aclFeatures":[],"eventIds":[],"backendRoutes":[]},"publicRoutes":0,"glyph":"0100000","lint":[{"code":"ships-tests","severity":"info","message":"The tarball ships test files.","anchor":null,"src":null},{"code":"version-drift","severity":"info","message":"ModuleInfo says 0.1.0, package.json says 0.9.0.","anchor":null,"src":{"file":"src/modules/telemetry/index.ts","line":7}}]}],"coverage":{"routesAuthResolved":1,"integrationTs":"absent"},"diagnostics":[]},"receipts":[],"rules":[{"id":"LST-1","pass":true,"detail":"Descriptor is valid."},{"id":"LST-2","pass":true,"detail":"Stable version exists and is not deprecated."},{"id":"LST-3","pass":true,"detail":"src/modules and dist/modules pair found."},{"id":"LST-4","pass":true,"detail":"License: MIT."},{"id":"LST-5","pass":true,"detail":"No known malware or open critical advisory."},{"id":"LST-6","pass":true,"detail":"Name reviewed at merge."},{"id":"VER-1","pass":false,"detail":"Not yet tested in a new app on 0.9."},{"id":"VER-2","pass":true,"detail":"Fits statically on 0.9: ok."},{"id":"VER-3","pass":true,"detail":"Supply chain: ok."},{"id":"VER-4","pass":true,"detail":"No lint errors."},{"id":"VER-5","pass":true,"detail":"No repository in the descriptor to compare."}],"maintainers":["pat-lewczuk","patryk.andrzejewski","piotrkarwatka"]}