{"_id":"@agent-qa/traces-tempo","name":"@agent-qa/traces-tempo","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@agent-qa/traces-tempo","version":"0.1.0","private":false,"type":"module","description":"Grafana Tempo traces provider for agent-qa framework","license":"MIT","main":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"dependencies":{"@agent-qa/core":"0.1.0"},"devDependencies":{"@types/node":"^22.0.0","@vitest/coverage-v8":"^4.0.16","typescript":"^5.7.3","vitest":"^4.0.3"},"scripts":{"build":"tsc -p tsconfig.json","type-check":"tsc --noEmit","lint":"eslint src/","lint:fix":"eslint src/ --fix","check":"pnpm lint && pnpm type-check","test":"vitest run","test:watch":"vitest","test:coverage":"vitest run --coverage","clean":"rm -rf dist"},"_id":"@agent-qa/traces-tempo@0.1.0","_integrity":"sha512-4sVgluhVHXOXL1nppOtYP8ih7WYTrateK9bvgYhdRIN6+jT2ujkSmiIagRJD/slaLj1TbzwSUtgn64UzHkEU/Q==","_resolved":"/tmp/7ccb398e9645734ef2878d2fd4baf528/agent-qa-traces-tempo-0.1.0.tgz","_from":"file:agent-qa-traces-tempo-0.1.0.tgz","_nodeVersion":"20.20.0","_npmVersion":"10.8.2","dist":{"integrity":"sha512-4sVgluhVHXOXL1nppOtYP8ih7WYTrateK9bvgYhdRIN6+jT2ujkSmiIagRJD/slaLj1TbzwSUtgn64UzHkEU/Q==","shasum":"002da75202a3aac7e25d5441ffe3ee9064c7ac6c","tarball":"https://registry.npmjs.org/@agent-qa/traces-tempo/-/traces-tempo-0.1.0.tgz","fileCount":31,"unpackedSize":58033,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQD8qQ+hGMFXoqccTXv1msx19cLCdcU44K/B1ndurcvuKwIhAN40Xf/+ArCr1XnINvgUY8X18dRYTTCmUUm8bdrI3Jyk"}]},"_npmUser":{"name":"tedjames24","email":"ted@agentdesk.ai"},"directories":{},"maintainers":[{"name":"tedjames24","email":"ted@agentdesk.ai"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/traces-tempo_0.1.0_1770054542696_0.008072357098001692"},"_hasShrinkwrap":false}},"time":{"created":"2026-02-02T17:49:02.631Z","0.1.0":"2026-02-02T17:49:02.889Z","modified":"2026-02-02T17:49:03.444Z"},"maintainers":[{"name":"tedjames24","email":"ted@agentdesk.ai"}],"description":"Grafana Tempo traces provider for agent-qa framework","license":"MIT","readme":"# @agent-qa/traces-tempo\n\nGrafana Tempo traces provider for the agent-qa framework.\n\n## Installation\n\n```bash\nnpm install @agent-qa/traces-tempo\n# or\npnpm add @agent-qa/traces-tempo\n```\n\n## Features\n\n- Implements the `TracesProvider` interface from `@agent-qa/core`\n- Fetch traces by ID or correlation ID\n- Search traces with filters (service, tags, time range)\n- Parse Tempo API responses into typed structures\n- Health check and status utilities\n\n## Usage with Agent-QA\n\nThe recommended way to use this package is with the agent-qa diagnostics config:\n\n```typescript\n// agentqa.config.ts\nimport { defineConfig } from '@agent-qa/core';\nimport { createTempoProvider } from '@agent-qa/traces-tempo';\n\nexport default defineConfig({\n  name: 'MyApp',\n  agent: { /* ... */ },\n  diagnostics: {\n    traces: {\n      provider: createTempoProvider({\n        url: 'http://localhost:3200',\n      }),\n    },\n  },\n});\n```\n\n## Standalone Usage\n\nYou can also use the provider directly:\n\n```typescript\nimport { createTempoProvider } from '@agent-qa/traces-tempo';\n\nconst provider = createTempoProvider({\n  url: 'http://localhost:3200',\n});\n\n// Check if Tempo is reachable\nconst reachable = await provider.isReachable();\n\n// Get trace by correlation ID\nconst trace = await provider.getTraceByCorrelationId('conv_abc123');\n\n// Search traces\nconst results = await provider.searchTraces({\n  service: 'my-api',\n  limit: 20,\n});\n```\n\n## Low-Level API\n\nFor advanced use cases, you can use the low-level client functions directly:\n\n### Fetch a Trace\n\n```typescript\nimport { fetchTrace, parseTempoResponse } from '@agent-qa/traces-tempo';\n\nconst response = await fetchTrace('trace-id-here');\nconst trace = parseTempoResponse(response);\n```\n\n### Search Traces\n\n```typescript\nimport { searchTraces, parseTimeRange } from '@agent-qa/traces-tempo';\n\nconst now = Math.floor(Date.now() / 1000);\nconst results = await searchTraces({\n  service: 'my-api',\n  start: now - parseTimeRange('1h'),\n  end: now,\n  limit: 20,\n});\n```\n\n### Search by Correlation ID\n\n```typescript\nimport { searchByCorrelationId } from '@agent-qa/traces-tempo';\n\n// Find all traces for a specific conversation/session\nconst traces = await searchByCorrelationId('conv_abc123', {\n  limit: 10,\n  since: 3600, // seconds\n});\n```\n\n### Check Tempo Status\n\n```typescript\nimport { isTempoReachable, getStatus } from '@agent-qa/traces-tempo';\n\nif (await isTempoReachable()) {\n  const status = await getStatus();\n  console.log('Tempo is healthy:', status);\n}\n```\n\n## Environment Variables\n\n| Variable | Description |\n|----------|-------------|\n| `TEMPO_URL` | Tempo API endpoint (default: `http://localhost:3200`) |\n| `TEMPO_TIMEOUT` | Request timeout in ms (default: `30000`) |\n\n## API Reference\n\n### Provider Factory\n\n```typescript\nimport { createTempoProvider, type TempoProviderConfig } from '@agent-qa/traces-tempo';\n\nconst provider = createTempoProvider({\n  url?: string;      // Tempo server URL\n  timeout?: number;  // Request timeout\n});\n```\n\n### Client Functions\n\n```typescript\nimport {\n  fetchTrace,\n  fetchTraces,\n  searchTraces,\n  searchByCorrelationId,\n  getTraceByCorrelationId,\n  isTempoReachable,\n  getStatus,\n  getConfig,\n  parseTimeRange,\n} from '@agent-qa/traces-tempo';\n```\n\n### Parser\n\n```typescript\nimport { parseTempoResponse } from '@agent-qa/traces-tempo';\n```\n\n### Types\n\n```typescript\nimport type {\n  // Provider types (from @agent-qa/core)\n  TracesProvider,\n  TracesProviderStatus,\n  TraceSearchOptions,\n\n  // Domain types (from @agent-qa/core)\n  ParsedTrace,\n  ParsedSpan,\n  TraceMetrics,\n  TraceSearchResult,\n  SpanType,\n  SpanStatus,\n\n  // Tempo-specific types\n  TempoProviderConfig,\n  TempoConfig,\n  SearchOptions,\n  TempoResponse,\n  TempoSearchResult,\n} from '@agent-qa/traces-tempo';\n```\n\n## Custom Providers\n\nThis package provides a Tempo implementation of the `TracesProvider` interface.\nYou can create your own providers for other backends (LangFuse, Jaeger, etc.):\n\n```typescript\nimport type { TracesProvider, ParsedTrace } from '@agent-qa/core/traces';\n\nconst myProvider: TracesProvider = {\n  name: 'my-backend',\n\n  async isReachable() {\n    // Check if your backend is reachable\n    return true;\n  },\n\n  async getTraceByCorrelationId(correlationId) {\n    // Fetch and convert trace to ParsedTrace format\n    return convertToParsedTrace(await fetchFromMyBackend(correlationId));\n  },\n\n  async searchTraces(options) {\n    // Search your backend\n    return convertToSearchResults(await searchMyBackend(options));\n  },\n};\n```\n\n## License\n\nMIT\n","readmeFilename":"README.md","_rev":"1-1d6f99660aafdab799b453ca301a770d"}