Tracing

Tracing provides OpenTelemetry-compatible spans with Dreadnode-specific metadata. Use TaskSpan for manual instrumentation or Tracer for automatic export to local logs or the platform.

Key types & signatures

class TaskSpan {
  constructor(options: { name: string; spanType?: SpanType; project?: string; label?: string });
  enter(): this;
  exit(error?: Error): void;
  run<T>(fn: (span: TaskSpan) => Promise<T>): Promise<T>;
  logInput(name: string, value: unknown): string;
  logOutput(name: string, value: unknown): string;
  logMetric(name: string, value: number, options?: { step?: number }): this;
  setStatus(status: SpanStatus, message?: string): this;
}

class Tracer {
  constructor(config?: TracerConfig);
  startTask(name: string, options?: { spanType?: SpanType }): TaskSpan;
  trackSpan(span: TaskSpan): void;
  flush(): Promise<void>;
  shutdown(): Promise<void>;
}

function configureDreadnode(config: DreadnodeConfig): Tracer;

Manual spans

import { taskSpan } from '@dreadnode/agents';

const span = taskSpan('data-prep').enter();
try {
  span.logInput('rows', 250);
  // ... work
  span.logOutput('status', 'ok');
  span.setStatus('ok');
} finally {
  span.exit();
}

Export to the Dreadnode platform

import { configureDreadnode, taskSpan } from '@dreadnode/agents';

configureDreadnode({
  apiKey: process.env.DREADNODE_API_KEY!,
  org: 'acme',
  project: 'support-bots',
});

await taskSpan('support-ticket').run(async (span) => {
  span.logMetric('latency_ms', 112);
  return { ok: true };
});

Use exporters directly

import { DreadnodeExporter, OTLPExporter, Tracer } from '@dreadnode/agents';

const tracer = new Tracer({ backend: 'both' });

const dreadnode = new DreadnodeExporter({
  apiKey: process.env.DREADNODE_API_KEY!,
  org: 'acme',
});

const otlp = new OTLPExporter({
  url: 'https://otel-collector.acme.dev/v1/traces',
  apiKey: process.env.OTLP_API_KEY!,
  serviceName: 'dreadnode-agents',
});

await Promise.all([dreadnode.shutdown(), otlp.shutdown()]);
await tracer.shutdown();