opentelemetry

OpenTelemetry observability - use for distributed tracing, metrics, instrumentation, Sentry integration, and monitoring

⭐5stars🔀1forks📁View on GitHub🕐Updated Jan 11, 2026⬇️1downloads

When & Why to Use This Skill

This Claude skill provides comprehensive patterns and configurations for implementing OpenTelemetry observability across modern tech stacks. It enables developers to integrate distributed tracing, metrics collection, and Sentry error tracking into Spring Boot and Next.js applications, facilitating robust system monitoring and accelerated incident resolution through standardized telemetry data.

Use Cases

  • Implementing distributed tracing in Spring Boot microservices to visualize request flows and identify latency bottlenecks across service boundaries.
  • Instrumenting Next.js and Node.js applications with OpenTelemetry SDK to monitor full-stack performance and backend execution.
  • Correlating Sentry error reports with specific OpenTelemetry trace spans to provide deep context for debugging production exceptions.
  • Configuring OpenTelemetry Collectors to aggregate, process, and export telemetry data to multiple backends like Zipkin, Prometheus, and logging services.
  • Utilizing custom spans, metrics, and baggage propagation to track business-specific KPIs and maintain user context throughout complex asynchronous workflows.
nameopentelemetry
descriptionOpenTelemetry observability - use for distributed tracing, metrics, instrumentation, Sentry integration, and monitoring

OpenTelemetry Patterns

Spring Boot Configuration

// build.gradle.kts
dependencies {
    implementation(platform("io.opentelemetry.instrumentation:opentelemetry-instrumentation-bom:2.15.0"))
    implementation("io.opentelemetry.instrumentation:opentelemetry-spring-boot-starter")
    implementation("io.micrometer:micrometer-tracing-bridge-otel")
    implementation("io.opentelemetry:opentelemetry-exporter-zipkin")

    // Sentry integration
    implementation("io.sentry:sentry-spring-boot-starter-jakarta:8.26.0")
    implementation("io.sentry:sentry-logback:8.26.0")
}
# application.yaml
spring:
  application:
    name: orca-facade

management:
  tracing:
    sampling:
      probability: 1.0  # 100% in dev, lower in prod
  otlp:
    tracing:
      endpoint: http://localhost:4318/v1/traces

otel:
  exporter:
    otlp:
      endpoint: http://otel-collector:4317
  service:
    name: orca-facade
  resource:
    attributes:
      deployment.environment: ${ENVIRONMENT:dev}
      service.version: ${APP_VERSION:unknown}

sentry:
  dsn: ${SENTRY_DSN:}
  environment: ${ENVIRONMENT:dev}
  traces-sample-rate: 1.0

Custom Span Creation

import io.opentelemetry.api.trace.Span
import io.opentelemetry.api.trace.Tracer
import io.opentelemetry.context.Context
import org.springframework.stereotype.Component

@Component
class TracingService(
    private val tracer: Tracer
) {

    fun <T> withSpan(
        spanName: String,
        attributes: Map<String, String> = emptyMap(),
        block: () -> T
    ): T {
        val span = tracer.spanBuilder(spanName)
            .setParent(Context.current())
            .startSpan()

        attributes.forEach { (key, value) ->
            span.setAttribute(key, value)
        }

        return try {
            span.makeCurrent().use {
                block()
            }
        } catch (e: Exception) {
            span.recordException(e)
            span.setStatus(io.opentelemetry.api.trace.StatusCode.ERROR, e.message ?: "Error")
            throw e
        } finally {
            span.end()
        }
    }
}

// Usage
@Service
class EnvironmentService(
    private val tracingService: TracingService,
    private val repository: EnvironmentRepository
) {

    fun createEnvironment(request: CreateRequest): Environment {
        return tracingService.withSpan(
            "EnvironmentService.createEnvironment",
            mapOf(
                "environment.name" to request.name,
                "user.id" to request.userId
            )
        ) {
            // Add events
            Span.current().addEvent("Validating request")
            validateRequest(request)

            Span.current().addEvent("Saving to database")
            repository.save(request.toEntity())
        }
    }
}

Annotation-Based Tracing

import io.micrometer.tracing.annotation.NewSpan
import io.micrometer.tracing.annotation.SpanTag

@Service
class ComputeService {

    @NewSpan("compute.createInstance")
    fun createInstance(
        @SpanTag("instance.type") type: String,
        @SpanTag("instance.region") region: String
    ): Instance {
        // Automatically traced
        return computeClient.create(type, region)
    }
}

Baggage Propagation

import io.opentelemetry.api.baggage.Baggage

// Set baggage (propagates across services)
fun setUserContext(userId: String, tenantId: String) {
    Baggage.current()
        .toBuilder()
        .put("user.id", userId)
        .put("tenant.id", tenantId)
        .build()
        .makeCurrent()
}

// Read baggage
fun getCurrentUserId(): String? {
    return Baggage.current().getEntryValue("user.id")
}

Next.js / Node.js Setup

// instrumentation.ts (Next.js)
import { NodeSDK } from '@opentelemetry/sdk-node'
import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node'
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http'
import { Resource } from '@opentelemetry/resources'
import { SEMRESATTRS_SERVICE_NAME, SEMRESATTRS_SERVICE_VERSION } from '@opentelemetry/semantic-conventions'

export async function register() {
  if (process.env.NEXT_RUNTIME === 'nodejs') {
    const sdk = new NodeSDK({
      resource: new Resource({
        [SEMRESATTRS_SERVICE_NAME]: 'orca-lab',
        [SEMRESATTRS_SERVICE_VERSION]: process.env.npm_package_version || 'unknown',
      }),
      traceExporter: new OTLPTraceExporter({
        url: process.env.OTEL_EXPORTER_OTLP_ENDPOINT || 'http://localhost:4318/v1/traces',
      }),
      instrumentations: [
        getNodeAutoInstrumentations({
          '@opentelemetry/instrumentation-fs': { enabled: false },
        }),
      ],
    })

    sdk.start()
  }
}
// lib/tracing.ts
import { trace, SpanStatusCode, context } from '@opentelemetry/api'

const tracer = trace.getTracer('orca-lab')

export async function withSpan<T>(
  name: string,
  attributes: Record<string, string>,
  fn: () => Promise<T>
): Promise<T> {
  return tracer.startActiveSpan(name, async (span) => {
    try {
      Object.entries(attributes).forEach(([key, value]) => {
        span.setAttribute(key, value)
      })

      const result = await fn()
      span.setStatus({ code: SpanStatusCode.OK })
      return result
    } catch (error) {
      span.setStatus({
        code: SpanStatusCode.ERROR,
        message: error instanceof Error ? error.message : 'Unknown error',
      })
      span.recordException(error as Error)
      throw error
    } finally {
      span.end()
    }
  })
}

// Usage
export async function createEnvironment(data: CreateEnvInput) {
  return withSpan(
    'createEnvironment',
    { 'environment.name': data.name },
    async () => {
      const response = await fetch('/api/environments', {
        method: 'POST',
        body: JSON.stringify(data),
      })
      return response.json()
    }
  )
}

Metrics

// Kotlin/Spring Boot
import io.micrometer.core.instrument.MeterRegistry
import io.micrometer.core.instrument.Timer

@Component
class MetricsService(
    private val registry: MeterRegistry
) {

    private val environmentCreatedCounter = registry.counter(
        "orca.environment.created",
        "type", "standard"
    )

    private val environmentCreationTimer = Timer.builder("orca.environment.creation.duration")
        .description("Time to create an environment")
        .register(registry)

    fun recordEnvironmentCreated(type: String) {
        registry.counter("orca.environment.created", "type", type).increment()
    }

    fun <T> timeEnvironmentCreation(block: () -> T): T {
        return environmentCreationTimer.recordCallable(block)!!
    }
}

Sentry Integration

// Error reporting with Sentry
import io.sentry.Sentry
import io.sentry.SentryLevel

@ControllerAdvice
class GlobalExceptionHandler {

    @ExceptionHandler(Exception::class)
    fun handleException(e: Exception): ResponseEntity<ErrorResponse> {
        // Report to Sentry with context
        Sentry.withScope { scope ->
            scope.setTag("error.type", e.javaClass.simpleName)
            scope.setLevel(SentryLevel.ERROR)
            scope.setContexts("request", mapOf(
                "path" to getCurrentRequestPath(),
                "method" to getCurrentRequestMethod()
            ))
            Sentry.captureException(e)
        }

        return ResponseEntity.status(500)
            .body(ErrorResponse("Internal server error"))
    }
}

OpenTelemetry Collector Config

# otel-collector-config.yaml
receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
      http:
        endpoint: 0.0.0.0:4318

processors:
  batch:
    timeout: 1s
    send_batch_size: 1024

exporters:
  zipkin:
    endpoint: http://zipkin:9411/api/v2/spans
  prometheus:
    endpoint: 0.0.0.0:8889
  logging:
    loglevel: debug

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [zipkin, logging]
    metrics:
      receivers: [otlp]
      processors: [batch]
      exporters: [prometheus]