Skip to content

Overview

OpenTelemetry SDKs for Sematext Tracing

Sematext Tracing uses OpenTelemetry, the vendor-neutral observability standard, to collect traces from your applications. This section provides comprehensive guides for instrumenting applications in various programming languages.

Looking for working examples? Check out our Sematext OpenTelemetry Examples Repository for complete, ready-to-run examples with auto and manual instrumentation for Baremetal, Docker, and Kubernetes environments.

Language Framework Examples
Java Spring Boot java/
Python Flask python/
Node.js Express nodejs/
.NET ASP.NET Core dotnet/

How It Works

Your Application → OpenTelemetry SDK → Sematext Agent → Sematext Cloud

  1. Your Application: Instrumented with OpenTelemetry SDK using one of two approaches:

    • Auto-Instrumentation: Automatic trace capture with zero or minimal code changes - only configuration needed
    • Manual Instrumentation: Explicit code changes to create spans and add trace context

  2. OpenTelemetry SDK: Captures traces from your application and sends them via OTLP protocol

  3. Sematext Agent: Receives traces via OTLP receiver and securely forwards them to Sematext Cloud

  4. Sematext Cloud: Stores, analyzes, and visualizes your traces

Instrumentation Approaches

Auto-Instrumentation (Recommended for most use cases):

  • Zero to minimal code changes required
  • Automatic detection and instrumentation of popular frameworks and libraries
  • Only configuration changes needed (environment variables, agent setup)
  • Best for: Getting started quickly, standard application stacks

Manual Instrumentation (Advanced use cases):

  • Explicit code changes to create custom spans
  • Fine-grained control over trace data and span attributes
  • Required for custom business logic tracing
  • Best for: Complex applications, custom frameworks, detailed business metrics

Important: The Sematext Agent with OTLP support is required for all SDK configurations. The agent acts as a local collector that receives traces from your application and securely forwards them to Sematext Cloud.

Supported Languages

These languages have excellent auto-instrumentation support, making them ideal for getting started quickly. Manual instrumentation is also available for advanced use cases:

Java
  • Auto-instrumentation: Java agent with zero code changes
  • Frameworks: Spring Boot, Tomcat, Jetty, and more
  • Libraries: JDBC, HTTP clients, messaging systems
  • Kotlin Support: Full compatibility with Kotlin applications
Python
  • Auto-instrumentation: One-command setup with opentelemetry-instrument
  • Frameworks: Django, Flask, FastAPI, Tornado
  • Libraries: SQLAlchemy, Redis, PostgreSQL, MySQL, requests
  • Async Support: Full async/await compatibility
Node.js
  • Auto-instrumentation: Automatic framework detection
  • Frameworks: Express, Koa, Fastify, HTTP/HTTPS
  • Libraries: MongoDB, PostgreSQL, Redis, HTTP clients
  • TypeScript: Full TypeScript support with type definitions
.NET
  • Auto-instrumentation: .NET automatic instrumentation
  • Frameworks: ASP.NET Core, console apps, worker services
  • Libraries: Entity Framework, HTTP clients, SQL Server
  • Platforms: .NET Core, .NET Framework, .NET 5+
Browser JavaScript
  • Auto-instrumentation: Automatic web instrumentation with getWebAutoInstrumentations()
  • Frameworks: React, Vue.js, Angular, vanilla JavaScript
  • Features: User interaction tracking, API call tracing, fetch/XHR instrumentation
  • Deployment: Web server proxy, backend API proxy, development proxy
Android
  • Auto-instrumentation: OkHttp, Retrofit, Room database via OpenTelemetry Android agent
  • Languages: Java and Kotlin
  • Features: Activity lifecycle tracking, network requests, user interactions
  • Platform: Android 5.0+ (API level 21+)
  • Requires backend proxy for trace export

Manual Instrumentation Focused

These languages typically require manual instrumentation, though some limited auto-instrumentation may be available:

iOS/Swift
  • Manual instrumentation: Swift SDK with explicit span creation
  • Frameworks: SwiftUI and UIKit support
  • Features: View lifecycle tracking, URLSession instrumentation, user interactions
  • Platform: iOS 13.0+, macOS 10.15+, tvOS 13.0+, watchOS 6.0+
  • Requires backend proxy for trace export
Go
  • Manual instrumentation: Easy-to-use instrumentation libraries
  • Frameworks: Gin, Echo, HTTP server/client
  • Libraries: SQL databases, Redis, gRPC
  • Performance: Minimal overhead with excellent performance
Ruby
  • Framework Support: Rails, Sinatra with some auto-instrumentation
  • Libraries: ActiveRecord, Redis, HTTP clients, background jobs
  • Flexibility: Fine-grained control over span creation

Other Languages

Don't see your language? OpenTelemetry supports many more languages:

  • PHP: OpenTelemetry PHP with framework support
  • Rust: Growing ecosystem with basic instrumentation
  • C++: Core OpenTelemetry C++ SDK
  • Erlang/Elixir: Community-driven instrumentations

For languages not covered in detail, you can:

  1. Use the OpenTelemetry documentation for your language
  2. Configure OTLP export to http://localhost:4338 (HTTP) or http://localhost:4337 (gRPC)
  3. Contact support@sematext.com for guidance

Quick Setup Overview

All SDK configurations follow a similar pattern:

1. Install OpenTelemetry Dependencies

Each language has its own package manager and dependencies:

# Java
wget opentelemetry-javaagent.jar

# Python  
pip install opentelemetry-distro[otlp]

# Node.js
npm install @opentelemetry/auto-instrumentations-node

# Go
go get go.opentelemetry.io/otel

# .NET
dotnet add package OpenTelemetry.Exporter.OpenTelemetryProtocol

# Ruby
gem install opentelemetry-sdk opentelemetry-exporter-otlp

2. Configure OTLP Export

Point your application to the Sematext Agent: 

export OTEL_SERVICE_NAME=your-service-name
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4338
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf

3. Run Your Application

Execute with tracing enabled: 

# Java
java -javaagent:opentelemetry-javaagent.jar -jar app.jar

# Python
opentelemetry-instrument python app.py

# Node.js  
node -r ./tracing.js app.js

# Others: varies by language

Agent Requirement

Critical: All applications require the Sematext Agent to be running with OpenTelemetry support enabled.

The agent provides:

  • OTLP Receiver: Accepts traces from your applications
  • Security: Secure communication to Sematext Cloud
  • Reliability: Buffering and retry logic
  • Performance: Local collection reduces application overhead

Example Applications

Complete working examples for all supported languages are available in our public repository:

🔗 Sematext OpenTelemetry Examples

The repository includes:

  • Ready-to-run applications for each language
  • Configuration examples for different frameworks
  • Best practices and common patterns
  • Integration examples with databases, message queues, and HTTP clients

Common Configuration

OTLP Endpoints

  • HTTP (Recommended): http://localhost:4338
  • gRPC: http://localhost:4337
  • Protocol: http/protobuf for HTTP, grpc for gRPC

Service Configuration

# Required
export OTEL_SERVICE_NAME=your-service-name

# Optional but recommended
export OTEL_SERVICE_VERSION=1.0.0
export OTEL_RESOURCE_ATTRIBUTES=environment=production,team=backend

Sampling Configuration

# Sample all traces (development)
export OTEL_TRACES_SAMPLER=always_on

# Sample 10% of traces (production)
export OTEL_TRACES_SAMPLER=traceidratio
export OTEL_TRACES_SAMPLER_ARG=0.1

Feature Comparison

Language Auto-Instrumentation Manual Spans Async Support Framework Coverage Performance
Java ✅ Excellent ✅ Full ✅ Yes ✅ Comprehensive ⚡ Excellent
Python ✅ Excellent ✅ Full ✅ Yes ✅ Comprehensive ⚡ Good
Node.js ✅ Excellent ✅ Full ✅ Native ✅ Comprehensive ⚡ Excellent
.NET ✅ Good ✅ Full ✅ Yes ✅ Good ⚡ Excellent
Go ⚠️ Manual ✅ Full ✅ Yes ⚡ Growing ⚡ Excellent
Ruby ⚠️ Limited ✅ Full ✅ Partial ⚡ Good ⚡ Good

Best Practices

Service Naming

  • Use descriptive, consistent names
  • Include environment: api-prod, worker-staging
  • Follow your organization's naming conventions

Sampling Strategy

  • Development: Use always_on for complete visibility
  • Production: Use traceidratio (typically 0.01-0.1)
  • High-traffic services: Lower sampling rates (0.001-0.01)

Resource Attributes

Always include: 

export OTEL_RESOURCE_ATTRIBUTES=\
environment=${ENV},\
service.version=${VERSION},\
deployment.environment=${ENVIRONMENT}

Error Handling

  • Always record exceptions in spans
  • Set appropriate span status codes
  • Include relevant error context as attributes

Getting Help

Documentation

Examples and Code

Support

Next Steps

  1. Choose Your Language: Select your programming language from the list above
  2. Install Sematext Agent: Set up the agent with OpenTelemetry support
  3. Follow SDK Guide: Complete the language-specific instrumentation guide
  4. Explore Examples: Check out the examples repository
  5. View Your Traces: Start analyzing traces in Sematext Cloud

The OpenTelemetry-based approach provides excellent performance, broad language support, and vendor-neutral instrumentation that works with any observability platform.