getTracer()

Get the underlying OpenTelemetry tracer instance

Overview

getTracer() returns the underlying OpenTelemetry tracer for advanced use cases where you need direct access to OpenTelemetry APIs.

Signature

1getTracer(): Tracer

Basic Usage

1import { RespanTelemetry } from '@respan/tracing';
2
3const respanAi = new RespanTelemetry({
4 apiKey: process.env.RESPAN_API_KEY,
5 appName: 'my-app'
6});
7
8await respanAi.initialize();
9
10const client = respanAi.getClient();
11const tracer = client.getTracer();
12
13// Now you have access to the OpenTelemetry tracer
14console.log('Tracer:', tracer);

Manual Span Creation

1await respanAi.withWorkflow(
2 { name: 'custom_workflow' },
3 async () => {
4 const client = respanAi.getClient();
5 const tracer = client.getTracer();
6
7 // Manually create a span using OpenTelemetry API
8 const span = tracer.startSpan('custom_operation');
9
10 try {
11 const result = await performOperation();
12 span.setStatus({ code: 1 }); // OK
13 return result;
14 } catch (error) {
15 span.setStatus({ code: 2 }); // ERROR
16 span.recordException(error);
17 throw error;
18 } finally {
19 span.end();
20 }
21 }
22);

Advanced Context Management

1import { context, trace } from '@opentelemetry/api';
2
3await respanAi.withWorkflow(
4 { name: 'advanced_workflow' },
5 async () => {
6 const client = respanAi.getClient();
7 const tracer = client.getTracer();
8
9 // Create a new span with custom context
10 const span = tracer.startSpan('custom_span');
11 const ctx = trace.setSpan(context.active(), span);
12
13 // Run code within custom context
14 await context.with(ctx, async () => {
15 await performWork();
16 });
17
18 span.end();
19 }
20);
1await respanAi.withWorkflow(
2 { name: 'linked_workflow' },
3 async () => {
4 const client = respanAi.getClient();
5 const tracer = client.getTracer();
6
7 // Create a span with links to other traces
8 const span = tracer.startSpan('linked_operation', {
9 links: [
10 {
11 context: {
12 traceId: 'previous-trace-id',
13 spanId: 'previous-span-id',
14 traceFlags: 1
15 }
16 }
17 ]
18 });
19
20 await performLinkedOperation();
21
22 span.end();
23 }
24);

When to Use

For most use cases, prefer the high-level methods (withWorkflow, withTask, withAgent, withTool) over direct tracer access.

Use getTracer() when you need to:

  • Create spans with custom OpenTelemetry options
  • Implement advanced context propagation
  • Add span links to external traces
  • Integrate with custom OpenTelemetry instrumentation
  • Use OpenTelemetry features not exposed by Respan SDK

Return Value

Returns the OpenTelemetry Tracer instance.

Best Practices

  • Prefer Respan’s high-level methods for standard tracing
  • Use getTracer() only for advanced OpenTelemetry features
  • Always call span.end() when manually creating spans
  • Handle errors properly when manually managing spans
  • Consult OpenTelemetry documentation for tracer API details