{"_id":"@dongkseo/otel","_rev":"4-c956cc9a03592bf6662d4183fa7b57f7","name":"@dongkseo/otel","dist-tags":{"latest":"0.1.3"},"versions":{"0.1.0":{"name":"@dongkseo/otel","version":"0.1.0","_id":"@dongkseo/otel@0.1.0","maintainers":[{"name":"dongkseo","email":"ssddgg99@daum.net"}],"dist":{"shasum":"2ae9ab0328b4ea0e0e636bc28d924dfac933b402","tarball":"https://registry.npmjs.org/@dongkseo/otel/-/otel-0.1.0.tgz","fileCount":14,"integrity":"sha512-bhmZKEnxMMM4PK/wOOuU/N28wGmbVDqIDxCrxrowySIhYZac8uHZxaqk0rK9h5+wGqBD8lqAjlLaPOErOIQ1rA==","signatures":[{"sig":"MEUCIHh3xObmzqew1wamiMbz6kErHDR1ZZeT5OqiOnHgwahSAiEAudQ0cKIk5MTr5Yzi+psL+JmaifStCJ013qhzVyMwwBE=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":27239},"main":"./dist/index.js","type":"module","_from":"file:dongkseo-otel-0.1.0.tgz","types":"./dist/index.d.ts","nexora":{"stability":"advanced"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"scripts":{"test":"vitest run","build":"tsc","clean":"rm -rf dist .tsbuildinfo"},"_npmUser":{"name":"dongkseo","email":"ssddgg99@daum.net"},"_resolved":"/private/var/folders/lw/t8yfg__j2nxd25m53gt8840h0000gn/T/b894094c51d33679b18a1a21a3d275ee/dongkseo-otel-0.1.0.tgz","_integrity":"sha512-bhmZKEnxMMM4PK/wOOuU/N28wGmbVDqIDxCrxrowySIhYZac8uHZxaqk0rK9h5+wGqBD8lqAjlLaPOErOIQ1rA==","_npmVersion":"11.12.1","description":"**Stability: stable**","directories":{},"_nodeVersion":"26.0.0","dependencies":{"@opentelemetry/api":"^1.9.0","@dongkseo/contracts":"0.1.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.8.0","@types/node":"^22.0.0"},"_npmOperationalInternal":{"tmp":"tmp/otel_0.1.0_1781668539044_0.3341262200353985","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@dongkseo/otel","version":"0.1.1","_id":"@dongkseo/otel@0.1.1","maintainers":[{"name":"dongkseo","email":"ssddgg99@daum.net"}],"dist":{"shasum":"88b40b0ddd8af27e3ea27a06ee412b067f058b53","tarball":"https://registry.npmjs.org/@dongkseo/otel/-/otel-0.1.1.tgz","fileCount":14,"integrity":"sha512-QzDwuQloImHK+Mfxrb4wJTKUN8Q8xI2sWEc/BiITyfAhj7LtwMzCkutlAk9J/V5O1JxDT3+fglX2D3SkdqmIJg==","signatures":[{"sig":"MEQCIDxDsdRenHoZYkQW9M3I2mJ0GwVpOfo5YnIhF1LkBEDmAiA4yT3MUnrHcWJAjPf263dCUfkOccXrHYHouxD39lUQGA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":27240},"main":"./dist/index.js","type":"module","_from":"file:dongkseo-otel-0.1.1.tgz","types":"./dist/index.d.ts","nexora":{"stability":"advanced"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"scripts":{"test":"vitest run","build":"tsc","clean":"rm -rf dist .tsbuildinfo"},"_npmUser":{"name":"dongkseo","email":"ssddgg99@daum.net"},"_resolved":"/private/var/folders/f6/dfc3mm717vx9xjh0vbgqnddr0000gn/T/dd375e1b6050a38924caca95814e03ef/dongkseo-otel-0.1.1.tgz","_integrity":"sha512-QzDwuQloImHK+Mfxrb4wJTKUN8Q8xI2sWEc/BiITyfAhj7LtwMzCkutlAk9J/V5O1JxDT3+fglX2D3SkdqmIJg==","_npmVersion":"11.12.1","description":"**Stability: stable**","directories":{},"_nodeVersion":"26.0.0","dependencies":{"@opentelemetry/api":"^1.9.0","@dongkseo/contracts":"^0.1.8"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.8.0","@types/node":"^22.0.0"},"_npmOperationalInternal":{"tmp":"tmp/otel_0.1.1_1782200179302_0.7770690349274658","host":"s3://npm-registry-packages-npm-production"}},"0.1.2":{"name":"@dongkseo/otel","version":"0.1.2","_id":"@dongkseo/otel@0.1.2","maintainers":[{"name":"dongkseo","email":"ssddgg99@daum.net"}],"dist":{"shasum":"7372660a442dcceb31435727600a98268a4f4a09","tarball":"https://registry.npmjs.org/@dongkseo/otel/-/otel-0.1.2.tgz","fileCount":14,"integrity":"sha512-USINtq3v3DIHuvkstB+ABi37YZMKffz2BwRqkdpwV4sqobv7yZ8BjzLw3L1rDlc3fiWdO1VUB6Jg4ftcYP40NQ==","signatures":[{"sig":"MEQCIGTt0AwLS4UlU+GBWU/QKezuAfcDdtzARE+d/DQTkWnCAiAaeAV7gqOa3YxXVg564DKnDWYRUkFPCAYm9mmhHDRiIQ==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":32592},"main":"./dist/index.js","type":"module","_from":"file:dongkseo-otel-0.1.2.tgz","types":"./dist/index.d.ts","nexora":{"stability":"advanced"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"scripts":{"test":"vitest run","build":"tsc","clean":"rm -rf dist .tsbuildinfo"},"_npmUser":{"name":"dongkseo","email":"ssddgg99@daum.net"},"_resolved":"/private/var/folders/lw/t8yfg__j2nxd25m53gt8840h0000gn/T/0cc1f478766a16705b5ffe27255fe560/dongkseo-otel-0.1.2.tgz","_integrity":"sha512-USINtq3v3DIHuvkstB+ABi37YZMKffz2BwRqkdpwV4sqobv7yZ8BjzLw3L1rDlc3fiWdO1VUB6Jg4ftcYP40NQ==","_npmVersion":"11.16.0","description":"**Stability: advanced** · `pnpm add @dongkseo/otel`","directories":{},"_nodeVersion":"26.3.1","dependencies":{"@opentelemetry/api":"^1.9.0","@dongkseo/contracts":"^0.1.11"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.8.0","@types/node":"^22.0.0"},"_npmOperationalInternal":{"tmp":"tmp/otel_0.1.2_1782389348006_0.674303498417612","host":"s3://npm-registry-packages-npm-production"}},"0.1.3":{"name":"@dongkseo/otel","version":"0.1.3","type":"module","main":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"dependencies":{"@opentelemetry/api":"^1.9.1","@dongkseo/contracts":"^0.1.32"},"devDependencies":{"@types/node":"^26.1.2","typescript":"^7.0.2"},"nexora":{"stability":"advanced"},"publishConfig":{"access":"public"},"scripts":{"build":"tsc","test":"vitest run","clean":"rm -rf dist .tsbuildinfo"},"_nodeVersion":"26.7.0","_id":"@dongkseo/otel@0.1.3","dist":{"integrity":"sha512-Yon2kZ35q6vGxvsinj2baWDY+5i6B2HeCn6h208FBwtaaVfH04QH0AzEbUs+P5bLfPf0xFioc1tBWm1NWjdqYA==","shasum":"15192f235377b34d31f67a8aa6036f3a3a5740cd","tarball":"https://registry.npmjs.org/@dongkseo/otel/-/otel-0.1.3.tgz","fileCount":14,"unpackedSize":32694,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIC1dDmr7G/4DoyVjQfXEgrx87IBIQLzPhikrPLkVjob6AiEAh1Qr9WtaOzoxhl56zNAvB2jSBegFKaTbwE8CsrNxQ+E="}]},"_npmUser":{"name":"dongkseo","email":"ssddgg99@daum.net"},"directories":{},"maintainers":[{"name":"dongkseo","email":"ssddgg99@daum.net"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/otel_0.1.3_1786622512983_0.9102665724307863"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-17T03:55:38.943Z","modified":"2026-08-13T12:01:53.277Z","0.1.0":"2026-06-17T03:55:39.230Z","0.1.1":"2026-06-23T07:36:19.455Z","0.1.2":"2026-06-25T12:09:08.142Z","0.1.3":"2026-08-13T12:01:53.140Z"},"maintainers":[{"name":"dongkseo","email":"ssddgg99@daum.net"}],"readme":"# @dongkseo/otel\n\n**Stability: advanced** · `pnpm add @dongkseo/otel`\n\nNexora를 OpenTelemetry로 계측하는 두 개의 어댑터. HTTP 요청 → 게이트웨이 → 트랜스포트 →\n에이전트 부트스트랩 → 아키텍처 루프 → 도구 호출 → 트랜스포트 응답까지를 **하나의 trace**로\nJaeger/Tempo/Honeycomb에서 볼 수 있게 한다.\n\n## 무엇인가 / 무엇이 아닌가\n\n이 패키지는 Nexora의 두 확장 지점에 span을 끼워 넣는 **얇은 계측 레이어**다. `@opentelemetry/api`\n(facade)에만 의존하며, 실제 SDK/exporter 설정은 하지 않는다.\n\n- ✅ `EventTransport`를 감싸 publish/subscribe/request마다 span 생성 (`OTelTransport`)\n- ✅ `MiddlewarePipeline` 플러그인으로 에이전트 실행 + 도구 호출 span 생성 (`createOTelAgentMiddleware`)\n- ✅ Nexora trace/span id를 W3C 포맷으로 변환해 trace 연속성 보장 (`@dongkseo/contracts`의 `toW3CTraceId` 활용)\n- ❌ OTLP/Jaeger/console exporter, `NodeSDK`, span processor 설정 — **애플리케이션 책임**\n- ❌ 메트릭/로그 계측 (span만 다룸)\n- ❌ 트랜스포트/미들웨어 구현 자체 — 기존 구현을 감싸기만 한다\n\n의존 방향: `@dongkseo/otel` → `@dongkseo/contracts`(타입·id 헬퍼) + `@opentelemetry/api`. 역방향 없음.\n\n## 핵심 개념\n\n| 개념 | 무엇 | 대표 export |\n| **Transport span** | publish/subscribe/request 경계마다 span을 찍는 트랜스포트 래퍼 | `OTelTransport`, `OTelTransportOptions` |\n| **Agent span** | 실행 단위 + 각 도구 호출 span을 찍는 미들웨어 플러그인 | `createOTelAgentMiddleware`, `OTelAgentMiddlewareOptions` |\n| **기본 속성** | 모든 span에 붙는 공통 attribute (service.name 등) | `defaultAttributes` (양쪽 옵션) |\n\n## 사용 레시피\n\n트랜스포트 감싸기 — 기존 `EventTransport` 구현을 한 줄로 래핑한다:\n\n```ts\nimport { OTelTransport } from '@dongkseo/otel';\nimport { trace } from '@opentelemetry/api';\n\n// inner: 기존 EventTransport 구현 (in-memory, NATS 등)\nconst transport = new OTelTransport(inner, {\n  tracer: trace.getTracer('nexora'),          // 생략 시 trace.getTracer('nexora')\n  defaultAttributes: {\n    'service.name': 'nexora-gateway',\n    'deployment.environment': 'prod',\n  },\n});\n// 이제 transport.publish/subscribe/request가 자동으로 span을 남긴다.\n```\n\n에이전트 실행 계측 — 미들웨어를 러너에 등록한다 (`AgentRunnerOptions.middlewares`):\n\n```ts\nimport { createOTelAgentMiddleware } from '@dongkseo/otel';\nimport { AgentRunner } from '@dongkseo/core';\n\nconst runner = new AgentRunner({\n  architecture,\n  llm,\n  tools,\n  middlewares: [\n    createOTelAgentMiddleware({\n      defaultAttributes: { 'service.name': 'nexora-agent' },\n    }),\n  ],\n});\n// 실행마다 execution span, 도구 호출마다 child span이 생긴다.\n```\n\n> exporter/SDK는 별도로 부트스트랩해야 한다 (애플리케이션 시작 시 `@opentelemetry/sdk-node` 등).\n> 이 패키지는 `@opentelemetry/api`로 span만 발행한다.\n\n## API 표면 (소스 안 열고 타입만)\n\n정확한 시그니처가 필요하면 구현 본문 대신 **signatures 모드**로만 읽어라:\n\n```\nctx_read(path=\"packages/otel/src/transport-middleware.ts\", mode=\"signatures\")\nctx_read(path=\"packages/otel/src/agent-middleware.ts\",     mode=\"signatures\")\nctx_read(path=\"packages/otel/src/index.ts\",                mode=\"map\")   # 전체 export 목록\n```\n\n어떤 파일에 뭐가 있는지는 `src/index.ts` 상단 주석 맵을 먼저 보면 된다.\n\n## 유지보수 (drift 방지)\n\n- 이 README = **목적·개념·레시피** 만. 거의 안 변하므로 손으로 관리.\n- **API 정본은 각 소스의 TSDoc** (`/** … */`). API가 바뀌면 코드 옆 TSDoc만 고치면 됨 — 여기 표는 복제하지 말 것.\n- 새 모듈을 export하면 `index.ts` 상단 섹션 맵에 한 줄만 추가.\n\n## Tests\n\n```bash\ncd packages/otel && pnpm test\n```\n\nPart of the [Nexora](../../README.md) multi-tenant agent framework. · [Package map](../../docs/architecture/packages-map.md)\n","readmeFilename":""}