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.

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.