{"_id":"@emmett-community/emmett-observability","_rev":"6-f89b3625b345f943091165212af310a1","name":"@emmett-community/emmett-observability","dist-tags":{"latest":"0.3.0"},"versions":{"0.1.1":{"name":"@emmett-community/emmett-observability","version":"0.1.1","keywords":["emmett","observability","logging","tracing","opentelemetry","pino"],"author":{"name":"Andre X Costa"},"license":"MIT","_id":"@emmett-community/emmett-observability@0.1.1","maintainers":[{"name":"axcosta","email":"axcosta@gmail.com"}],"homepage":"https://github.com/emmett-community/emmett-observability#readme","bugs":{"url":"https://github.com/emmett-community/emmett-observability/issues"},"dist":{"shasum":"7a6a441dd75fe1fae0353f2fc2b780e4f9d2994e","tarball":"https://registry.npmjs.org/@emmett-community/emmett-observability/-/emmett-observability-0.1.1.tgz","fileCount":31,"integrity":"sha512-7HdyL8yORKNruCWGk7LT+h3tVpEuEWs1SL+zMbcACLNQkpHoTYDrTACE5c1lYyW36SFqXCOH9a1nYu1QE45Udw==","signatures":[{"sig":"MEUCIQDgICuJwgvqaPwwLf5jm0RciVXoGt+KwChulxaIwAYmZgIgTNl2eiwQ03MRSinn8GocEsJpcaVsOzNeQEcAwqeT8xQ=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":41909},"main":"./dist/index.cjs","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","exports":{".":{"import":{"types":"./dist/index.d.ts","default":"./dist/index.js"},"require":{"types":"./dist/index.d.cts","default":"./dist/index.cjs"}}},"gitHead":"8c8bc4fd46a856a9cc6308a6748137f0eaf3b7e8","scripts":{"test":"run-s test:unit test:int test:e2e","build":"tsup","build:ts":"tsc","test:e2e":"glob -c \"node --import tsx --import tsx/cjs --test\" \"test/e2e/**/*.e2e.spec.ts\"","test:int":"glob -c \"node --import tsx --import tsx/cjs --test\" \"test/integration/**/*.int.spec.ts\"","test:unit":"glob -c \"node --import tsx --import tsx/cjs --test\" \"test/unit/**/*.unit.spec.ts\"","test:watch":"node --import tsx --import tsx/cjs --test --watch","build:ts:watch":"tsc -b --watch","test:e2e:watch":"glob -c \"node --import tsx --import tsx/cjs --test --watch\" \"test/e2e/**/*.e2e.spec.ts\"","test:int:watch":"glob -c \"node --import tsx --import tsx/cjs --test --watch\" \"test/integration/**/*.int.spec.ts\"","test:unit:watch":"glob -c \"node --import tsx --import tsx/cjs --test --watch\" \"test/unit/**/*.unit.spec.ts\""},"_npmUser":{"name":"axcosta","email":"axcosta@gmail.com"},"repository":{"url":"git+https://github.com/emmett-community/emmett-observability.git","type":"git"},"_npmVersion":"11.6.2","description":"Application-level observability helpers for Emmett apps (logging + tracing)","directories":{},"sideEffects":false,"_nodeVersion":"24.12.0","dependencies":{"pino":"^8.21.0","@opentelemetry/api":"^1.9.0","@opentelemetry/sdk-node":"^0.52.0","@opentelemetry/resources":"^1.30.0","@opentelemetry/sdk-trace-base":"^1.30.0","@opentelemetry/semantic-conventions":"^1.30.0","@opentelemetry/exporter-trace-otlp-http":"^0.52.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.17.0","glob":"^11.0.0","tsup":"^8.2.4","typescript":"^5.5.4","@types/node":"^22.10.1","pino-pretty":"^13.1.3","npm-run-all2":"^6.2.2"},"_npmOperationalInternal":{"tmp":"tmp/emmett-observability_0.1.1_1767126340583_0.683623374849109","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@emmett-community/emmett-observability","version":"0.2.0","keywords":["emmett","observability","logging","tracing","opentelemetry","pino"],"author":{"name":"Andre X Costa"},"license":"MIT","_id":"@emmett-community/emmett-observability@0.2.0","maintainers":[{"name":"axcosta","email":"axcosta@gmail.com"}],"homepage":"https://github.com/emmett-community/emmett-observability#readme","bugs":{"url":"https://github.com/emmett-community/emmett-observability/issues"},"dist":{"shasum":"ff5255f5cbe99927233dc5622606af09678ba8c9","tarball":"https://registry.npmjs.org/@emmett-community/emmett-observability/-/emmett-observability-0.2.0.tgz","fileCount":9,"integrity":"sha512-bgv+buAEHTnEa9G8GzzznHj0Nq+rzF4tG9JR9NB7EjTdzNTvBM5upAMtVT+fG7OMeUh4jKaNqczCqFgIN+vx+Q==","signatures":[{"sig":"MEUCIQDa0wy/YqzlN/darn9z1LMpQVNDnN/U9LeItQka+KzgqQIgWUK1OutW0KKkYq/Fias+4jOw9uzvO6lhvKHYSktDB5M=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@emmett-community%2femmett-observability@0.2.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":40119},"main":"./dist/index.cjs","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","exports":{".":{"import":{"types":"./dist/index.d.ts","default":"./dist/index.js"},"require":{"types":"./dist/index.d.cts","default":"./dist/index.cjs"}}},"gitHead":"b4fdd987a33b48a92461bbe465f595d3dfc68b38","scripts":{"test":"run-s test:unit test:int test:e2e","build":"tsup","build:ts":"tsc","test:e2e":"glob -c \"node --import tsx --import tsx/cjs --test\" \"test/e2e/**/*.e2e.spec.ts\"","test:int":"glob -c \"node --import tsx --import tsx/cjs --test\" \"test/integration/**/*.int.spec.ts\"","test:unit":"glob -c \"node --import tsx --import tsx/cjs --test\" \"test/unit/**/*.unit.spec.ts\"","test:watch":"node --import tsx --import tsx/cjs --test --watch","build:ts:watch":"tsc -b --watch","test:e2e:watch":"glob -c \"node --import tsx --import tsx/cjs --test --watch\" \"test/e2e/**/*.e2e.spec.ts\"","test:int:watch":"glob -c \"node --import tsx --import tsx/cjs --test --watch\" \"test/integration/**/*.int.spec.ts\"","test:unit:watch":"glob -c \"node --import tsx --import tsx/cjs --test --watch\" \"test/unit/**/*.unit.spec.ts\""},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:98dc402b-cd62-4d9b-8a6c-173688b561bf"}},"repository":{"url":"git+https://github.com/emmett-community/emmett-observability.git","type":"git"},"_npmVersion":"11.6.2","description":"Application-level observability helpers for Emmett apps (logging + tracing)","directories":{},"sideEffects":false,"_nodeVersion":"24.12.0","dependencies":{"pino":"^8.21.0","@opentelemetry/api":"^1.9.0","@opentelemetry/sdk-node":"^0.52.0","@opentelemetry/resources":"^1.30.0","@opentelemetry/sdk-trace-base":"^1.30.0","@opentelemetry/semantic-conventions":"^1.30.0","@opentelemetry/exporter-trace-otlp-http":"^0.52.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.17.0","glob":"^11.0.0","tsup":"^8.2.4","typescript":"^5.5.4","@types/node":"^22.10.1","pino-pretty":"^13.1.3","npm-run-all2":"^6.2.2"},"_npmOperationalInternal":{"tmp":"tmp/emmett-observability_0.2.0_1767546796221_0.03185476976470225","host":"s3://npm-registry-packages-npm-production"}},"0.3.0":{"name":"@emmett-community/emmett-observability","version":"0.3.0","license":"MIT","type":"module","sideEffects":false,"description":"Application-level observability helpers for Emmett apps (logging + tracing)","scripts":{"build":"tsup","build:ts":"tsc","build:ts:watch":"tsc -b --watch","test":"run-s test:unit test:int test:e2e","test:unit":"glob -c \"node --import tsx --import tsx/cjs --test\" \"test/unit/**/*.unit.spec.ts\"","test:int":"glob -c \"node --import tsx --import tsx/cjs --test\" \"test/integration/**/*.int.spec.ts\"","test:e2e":"glob -c \"node --import tsx --import tsx/cjs --test\" \"test/e2e/**/*.e2e.spec.ts\"","test:watch":"node --import tsx --import tsx/cjs --test --watch","test:unit:watch":"glob -c \"node --import tsx --import tsx/cjs --test --watch\" \"test/unit/**/*.unit.spec.ts\"","test:int:watch":"glob -c \"node --import tsx --import tsx/cjs --test --watch\" \"test/integration/**/*.int.spec.ts\"","test:e2e:watch":"glob -c \"node --import tsx --import tsx/cjs --test --watch\" \"test/e2e/**/*.e2e.spec.ts\""},"repository":{"type":"git","url":"git+https://github.com/emmett-community/emmett-observability.git"},"keywords":["emmett","observability","logging","tracing","opentelemetry","pino"],"author":{"name":"Andre X Costa"},"bugs":{"url":"https://github.com/emmett-community/emmett-observability/issues"},"homepage":"https://github.com/emmett-community/emmett-observability#readme","exports":{".":{"import":{"types":"./dist/index.d.ts","default":"./dist/index.js"},"require":{"types":"./dist/index.d.cts","default":"./dist/index.cjs"}}},"main":"./dist/index.cjs","module":"./dist/index.js","types":"./dist/index.d.ts","dependencies":{"@opentelemetry/api":"^1.9.0","@opentelemetry/exporter-trace-otlp-http":"^0.52.0","@opentelemetry/resources":"^1.30.0","@opentelemetry/sdk-node":"^0.52.0","@opentelemetry/sdk-trace-base":"^1.30.0","@opentelemetry/semantic-conventions":"^1.30.0","pino":"^8.21.0"},"devDependencies":{"@types/node":"^22.10.1","glob":"^11.0.0","npm-run-all2":"^6.2.2","pino-pretty":"^13.1.3","tsup":"^8.2.4","tsx":"^4.17.0","typescript":"^5.5.4"},"publishConfig":{"access":"public"},"gitHead":"2897ae277a2302972458ad4989a92d937c017edb","_id":"@emmett-community/emmett-observability@0.3.0","_nodeVersion":"24.12.0","_npmVersion":"11.6.2","dist":{"integrity":"sha512-L6/X2v8FEWw2MaC27q5da+xdnsqrScwobNy4rF0nyA4WBxE5DwTNuLgg8Z/cCogjbs7wvLT3udIH0xU9jGABpQ==","shasum":"ac3ce1a5ccdbbfc22ec3430a484044c513cc9a37","tarball":"https://registry.npmjs.org/@emmett-community/emmett-observability/-/emmett-observability-0.3.0.tgz","fileCount":9,"unpackedSize":40177,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@emmett-community%2femmett-observability@0.3.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCICRlVdi+PC9AXjbZ2ow8LoJ0O+bpX63lsx/+qg9gN+KnAiEA47+19eO5BrCXOM7P/eY+TTe7s1TovucdTK7p1ZYNLx0="}]},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:98dc402b-cd62-4d9b-8a6c-173688b561bf"}},"directories":{},"maintainers":[{"name":"axcosta","email":"axcosta@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/emmett-observability_0.3.0_1767630308612_0.2627270910593218"},"_hasShrinkwrap":false}},"time":{"created":"2025-12-30T20:25:40.393Z","modified":"2026-01-05T16:25:09.147Z","0.1.0":"2025-12-30T18:38:10.030Z","0.1.1":"2025-12-30T20:25:40.725Z","0.2.0":"2026-01-04T17:13:16.365Z","0.3.0":"2026-01-05T16:25:08.769Z"},"bugs":{"url":"https://github.com/emmett-community/emmett-observability/issues"},"author":{"name":"Andre X Costa"},"license":"MIT","homepage":"https://github.com/emmett-community/emmett-observability#readme","keywords":["emmett","observability","logging","tracing","opentelemetry","pino"],"repository":{"type":"git","url":"git+https://github.com/emmett-community/emmett-observability.git"},"description":"Application-level observability helpers for Emmett apps (logging + tracing)","maintainers":[{"name":"axcosta","email":"axcosta@gmail.com"}],"readme":"# @emmett-community/emmett-observability\n\nApplication-level observability helpers for Emmett apps. This package wires OpenTelemetry tracing and Pino logging in a way that is explicit, opt-in, and friendly to application composition.\n\n[![npm version](https://img.shields.io/npm/v/@emmett-community/emmett-observability.svg)](https://www.npmjs.com/package/@emmett-community/emmett-observability) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Build and test](https://github.com/emmett-community/emmett-observability/actions/workflows/build_and_test.yml/badge.svg)](https://github.com/emmett-community/emmett-observability/actions/workflows/build_and_test.yml)\n\n## Features\n\n- ✅ Explicit tracing initialization (OTLP or console exporter)\n- ✅ Pino logger factory with trace correlation\n- ✅ Shared conventions for attributes and span naming\n- ✅ No side effects on import\n\n## Why this package exists\n\nApplications need consistent observability wiring without pulling in Emmett core packages or hiding OpenTelemetry concepts. This package provides a small, explicit layer that applications can opt into while keeping infrastructure concerns outside domain logic.\n\n## How it relates to other emmett-community packages\n\n- It is **only for applications**.\n- It is **not** a dependency of any emmett-* core packages (pubsub, firestore, express, etc).\n- It shares conventions with the rest of the ecosystem but stays decoupled from domain code.\n\n## Why it is optional\n\nObservability choices (tracing exporters, sampling, logger configuration) are infrastructure decisions that vary per application. This package keeps those decisions explicit and keeps imports silent by default.\n\n## Installation\n\n```bash\nnpm install @emmett-community/emmett-observability\n```\n\n## Quick start\n\n```typescript\nimport { initTracing, createLogger } from '@emmett-community/emmett-observability';\n\nconst shutdown = await initTracing({\n  serviceName: 'billing-api',\n  serviceVersion: '1.2.0',\n  environment: 'production',\n  exporter: { type: 'otlp', options: { url: 'http://localhost:4318/v1/traces' } },\n  sampling: { ratio: 1 },\n});\n\nconst logger = createLogger({\n  serviceName: 'billing-api',\n  environment: 'production',\n  logLevel: 'info',\n});\n\nlogger.info({ event: 'startup' }, 'service-ready');\n\nprocess.on('SIGTERM', async () => {\n  await shutdown();\n  process.exit(0);\n});\n```\n\n## Tracing\n\n```typescript\nimport { initTracing } from '@emmett-community/emmett-observability';\n\nconst shutdown = await initTracing({\n  serviceName: 'payments-api',\n  environment: 'staging',\n  exporter: { type: 'console' },\n  sampling: { ratio: 0.25, parentBased: true },\n});\n\n// ...start spans with @opentelemetry/api\n\nawait shutdown();\n```\n\n## Logging\n\n```typescript\nimport { context, trace } from '@opentelemetry/api';\nimport { createLogger } from '@emmett-community/emmett-observability';\n\nconst logger = createLogger({ serviceName: 'orders-api', environment: 'dev' });\nconst tracer = trace.getTracer('orders');\n\nconst span = tracer.startSpan('http.request');\ncontext.with(trace.setSpan(context.active(), span), () => {\n  logger.info({ route: '/health' }, 'request');\n  span.end();\n});\n```\n\nWhen tracing is active, log entries include `trace_id` and `span_id` fields.\n\n## Pretty logs (development)\n\nBy default, logging outputs JSON. To enable pretty logs locally, set `LOG_PRETTY=true`. If `LOG_PRETTY` is not set, pretty logs are enabled when `NODE_ENV` is `development` or `test`. Production output remains JSON.\n\n```bash\nLOG_PRETTY=true node ./dist/index.js\n```\n\n## Conventions\n\n```typescript\nimport { createSpanName, LogAttributes } from '@emmett-community/emmett-observability';\n\nconst spanName = createSpanName({\n  component: 'http',\n  operation: 'request',\n  target: 'GET /health',\n});\n\n// LogAttributes.traceId => \"trace_id\"\n// LogAttributes.spanId => \"span_id\"\n```\n\n## Auto-instrumentation\n\nThis package does not auto-register instrumentations. If you want auto-instrumentation, register it explicitly in your application after initializing tracing:\n\n```typescript\nimport { registerInstrumentations } from '@opentelemetry/instrumentation';\nimport { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';\nimport { initTracing } from '@emmett-community/emmett-observability';\n\nawait initTracing({\n  serviceName: 'orders-api',\n  exporter: { type: 'otlp' },\n});\n\nregisterInstrumentations({\n  instrumentations: [getNodeAutoInstrumentations()],\n});\n```\n\n## What this package intentionally does NOT do\n\n- Initialize tracing or logging on import\n- Create spans for you automatically\n- Depend on any emmett-* core package\n- Depend on Google Cloud SDKs\n- Include domain logic or business rules\n- Hide OpenTelemetry concepts behind abstractions\n\n## Testing\n\n```bash\nnpm run test:unit\nnpm run test:int\nnpm run test:e2e\n```\n\n## Contributing\n\nContributions are welcome! Please:\n\n1. Fork the repository\n2. Create a feature branch\n3. Add tests for new functionality\n4. Ensure all tests pass\n5. Submit a pull request\n\n---\n\nMade with ❤️ by the Emmett Community\n","readmeFilename":"README.md"}