Opentelemetry Tracing

Manual Span Creation

import { trace } from '@opentelemetry/api';

const tracer = trace.getTracer('my-service');

async function complexOperation(data: Data) {
  return tracer.startActiveSpan('complexOperation', async (span) => {
    try {
      span.setAttribute('data.id', data.id);
      const result = await doWork(data);
      span.setStatus({ code: SpanStatusCode.OK });
      return result;
    } catch (error) {
      span.setStatus({
        code: SpanStatusCode.ERROR,
        message: error.message
      });
      span.recordException(error);
      throw error;
    } finally {
      span.end();
    }
  });
}

Adding Attributes

span.setAttribute('user.id', userId);
span.setAttribute('operation.type', 'fetch');
span.setAttribute('result.count', results.length);

Recording Events

span.addEvent('cache.miss', {
  'cache.key': cacheKey,
});

GraphQL Instrumentation

Resolver Tracing

The GraphQL server auto-instruments resolvers, but add context:

const resolvers = {
  Query: {
    users: async (_, args, context) => {
      const span = trace.getActiveSpan();
      span?.setAttribute('query.limit', args.limit);
      // ... resolver logic
    }
  }
};

DataSource Tracing

class UsersAPI extends RESTDataSource {
  async getUser(id: string) {
    return this.trace(
      { name: 'UsersAPI.getUser', attributes: { userId: id } },
      () => this.get(`/users/${id}`)
    );
  }
}

Best Practices

Do

• Add meaningful span names (verb + noun)
• Include relevant attributes
• Record exceptions properly
• End spans in finally blocks

Don't

• Create spans for trivial operations
• Include sensitive data in attributes
• Forget to end spans
• Over-instrument (too many spans)

Attributes to Include

Sentry Integration

Traces are automatically sent to Sentry when configured:

import * as Sentry from '@sentry/node';

Sentry.init({
  dsn: process.env.SENTRY_DSN,
  tracesSampleRate: 0.1,
  integrations: [
    new Sentry.Integrations.OpenTelemetry(),
  ],
});

Before Completing

• New operations have appropriate spans
• Span names are descriptive
• Relevant attributes are included
• Errors are properly recorded
• No sensitive data in traces