{"_id":"@arlopass/telemetry","name":"@arlopass/telemetry","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@arlopass/telemetry","version":"0.1.0","description":"Metrics, tracing helpers, and redaction utilities for Arlopass","license":"MIT","type":"module","publishConfig":{"access":"public","provenance":true},"repository":{"type":"git","url":"git+https://github.com/arlopass/arlopass.git","directory":"packages/telemetry"},"homepage":"https://github.com/arlopass/arlopass/tree/main/packages/telemetry#readme","bugs":{"url":"https://github.com/arlopass/arlopass/issues"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","default":"./dist/index.js"}},"main":"dist/index.js","types":"dist/index.d.ts","scripts":{"build":"tsc -p tsconfig.json","typecheck":"tsc -p tsconfig.json --noEmit","lint":"eslint \"src/**/*.ts\"","test":"vitest run --passWithNoTests"},"_id":"@arlopass/telemetry@0.1.0","gitHead":"524008c81190adecca51ec54fbe99d77ebdd056f","_nodeVersion":"22.22.1","_npmVersion":"10.9.4","dist":{"integrity":"sha512-B1VIPM9LKa3eH8qL5E+Pp9ofMlMn7UWCuC7XUIxc/jCzCbLqm+KZ0YUdxOFucAyecwCt+j/kSw7Lcky8QV4qZw==","shasum":"d0234710c862716d238c6c2889654482aaec3dac","tarball":"https://registry.npmjs.org/@arlopass/telemetry/-/telemetry-0.1.0.tgz","fileCount":18,"unpackedSize":41326,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@arlopass%2ftelemetry@0.1.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDSXVRhSwWew2n8bq8cG7/2Ff+47gbgx1qcNTMc6edQLAIgOnEpa+8Jl5vKkzBme6tp22YPnO1MpUgLeiJY+udTiXA="}]},"_npmUser":{"name":"davidszakacs","email":"szakacs_david@hotmail.com"},"directories":{},"maintainers":[{"name":"davidszakacs","email":"szakacs_david@hotmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/telemetry_0.1.0_1774820854090_0.2691954873658253"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-29T21:47:33.976Z","0.1.0":"2026-03-29T21:47:34.222Z","modified":"2026-03-29T21:47:34.634Z"},"maintainers":[{"name":"davidszakacs","email":"szakacs_david@hotmail.com"}],"description":"Metrics, tracing helpers, and redaction utilities for Arlopass","homepage":"https://github.com/arlopass/arlopass/tree/main/packages/telemetry#readme","repository":{"type":"git","url":"git+https://github.com/arlopass/arlopass.git","directory":"packages/telemetry"},"bugs":{"url":"https://github.com/arlopass/arlopass/issues"},"license":"MIT","readme":"# @arlopass/telemetry\n\nCollect metrics, propagate traces, and redact sensitive data across all Arlopass components. Zero dependencies.\n\n```ts\nimport { TelemetryMetrics, TelemetryTracing } from \"@arlopass/telemetry\";\n\nconst metrics = new TelemetryMetrics();\nconst counter = metrics.createCounter(\"arlopass.request.total\", { correlationId: \"req-1\", origin: \"https://app.acme.com\", providerId: \"ollama\" });\ncounter.add();\n\nconst tracing = new TelemetryTracing();\nconst result = await tracing.withSpan(\"arlopass.request\", { correlationId: \"req-1\", origin: \"https://app.acme.com\", providerId: \"ollama\" }, async (span) => {\n  span.addEvent(\"provider.dispatch\", { modelId: \"llama3.2\" });\n  const res = await doWork();\n  span.setStatus(\"ok\");\n  return res;\n});\n```\n\n---\n\n## API Reference\n\n### `TelemetryMetrics`\n\nCollects metric data points.\n\n```ts\nconst metrics = new TelemetryMetrics(options?: TelemetryMetricsOptions);\n```\n\n| Method | Returns | Description |\n|--------|---------|-------------|\n| `emit(input: EmitMetricInput)` | `MetricPoint` | Emit a single metric point |\n| `createCounter(name, metadata)` | `{ add(value?: number): MetricPoint }` | Create a counter instrument |\n| `createHistogram(name, metadata)` | `{ record(value: number): MetricPoint }` | Create a histogram instrument |\n| `getRecordedMetrics()` | `readonly MetricPoint[]` | Retrieve all emitted metrics |\n| `reset()` | `void` | Clear recorded metrics |\n\n```ts\ntype MetricPoint = {\n  name: TelemetryMetricName;\n  value: number;\n  unit: TelemetryMetricUnit;\n  timestamp: string;\n  metadata: MetricSignalMetadata;\n}\n```\n\n#### Metric Names (`TELEMETRY_METRIC_NAMES`)\n\n| Name | Unit |\n|------|------|\n| `arlopass.request.total` | count |\n| `arlopass.request.duration_ms` | milliseconds |\n| `arlopass.request.failure.total` | count |\n| `arlopass.stream.chunk.total` | count |\n| `arlopass.stream.interruption.total` | count |\n| `arlopass.retry.total` | count |\n| `arlopass.adapter.health` | ratio |\n\n---\n\n### `TelemetryTracing`\n\nTrace spans across trust boundaries.\n\n```ts\nconst tracing = new TelemetryTracing(options?: TelemetryTracingOptions);\n```\n\n| Method | Returns | Description |\n|--------|---------|-------------|\n| `startSpan(name, options)` | `TelemetrySpan` | Start a new span |\n| `withSpan(name, options, callback)` | `Promise<T>` | Execute callback within a span (auto-ends on completion) |\n| `getRecordedSpans()` | `readonly SpanRecord[]` | Retrieve all recorded spans |\n| `reset()` | `void` | Clear recorded spans |\n\n### `TelemetrySpan`\n\nSingle trace span with events and status.\n\n| Property/Method | Type | Description |\n|----------------|------|-------------|\n| `traceId` | `string` | Trace ID |\n| `spanId` | `string` | Span ID |\n| `addEvent(name, attributes?)` | `void` | Add a timestamped event to the span |\n| `setStatus(status)` | `void` | Set span status: `\"ok\"` or `\"error\"` |\n| `end(attributes?)` | `SpanRecord` | End the span and return the record |\n\n```ts\ntype SpanRecord = {\n  traceId: string;\n  spanId: string;\n  parentSpanId?: string;\n  name: TelemetrySpanName;\n  startedAt: string;\n  endedAt: string;\n  status: \"ok\" | \"error\";\n  metadata: TraceSignalMetadata;\n  attributes: TraceAttributes;\n  events: readonly SpanEvent[];\n}\n\ntype SpanEvent = { name: string; timestamp: string; attributes: TraceAttributes }\n```\n\n#### Span Names (`TELEMETRY_SPAN_NAMES`)\n\n`arlopass.request` | `arlopass.policy.decision` | `arlopass.provider.dispatch` | `arlopass.stream` | `arlopass.adapter.health`\n\n---\n\n### Redaction\n\nStrip sensitive data from logs and telemetry signals.\n\n| Function | Description |\n|----------|-------------|\n| `redactTelemetryValue(value: unknown, options?: TelemetryRedactionOptions): unknown` | Redact a single value |\n| `redactTelemetryRecord(record: Record<string, unknown>, options?: TelemetryRedactionOptions): Record<string, unknown>` | Redact all sensitive fields in a record |\n| `assertRequiredMetadataFields(metadata, requiredFields?)` | Throws if required metadata is missing |\n| `normalizeSignalMetadata(metadata?, options?)` | Normalize and whitelist metadata fields |\n\n```ts\nconst REDACTED_VALUE = \"[REDACTED]\";\nconst REQUIRED_SIGNAL_METADATA_FIELDS = [\"correlationId\", \"origin\", \"providerId\"];\nconst SAFE_SIGNAL_METADATA_FIELDS = [\"correlationId\", \"origin\", \"providerId\", \"modelId\", \"capability\", \"reasonCode\", \"outcome\", \"requestId\", \"sessionId\", \"status\", \"errorName\", \"errorType\"];\n```\n\n---\n\n### Dependencies\n\nNone.\n","readmeFilename":"README.md","_rev":"1-14ba599f18bf0225079a383c8fc4c193"}