TraceKit Ruby SDK

Official Ruby SDK for TraceKit APM - OpenTelemetry-based distributed tracing, metrics collection, and application performance monitoring for Ruby applications.

The SDK is production-ready with full support for distributed tracing, metrics, and code monitoring.

TraceKit Ruby SDK provides production-ready distributed tracing, metrics, and code monitoring capabilities for Ruby and Rails applications. Built on OpenTelemetry standards, it offers seamless integration with Rails through automatic Railtie configuration, comprehensive security scanning, and a lightweight metrics API for tracking application performance.

• OpenTelemetry-Native: Built on OpenTelemetry for maximum compatibility
• Distributed Tracing: Full support for distributed trace propagation across microservices
• Auto-Instrumentation: Automatic tracing for Rails, Rack, PostgreSQL, MySQL, Redis, Sidekiq, and HTTP clients
• Explicit Span Kinds: Server spans explicitly marked with kind: Server for proper trace classification
• Metrics API: Counter, Gauge, and Histogram metrics with automatic OTLP export
• Code Monitoring: Live production debugging with non-breaking snapshots
• Security Scanning: Automatic detection of sensitive data (PII, credentials)
• Local UI Auto-Detection: Automatically sends traces to local TraceKit UI
• Rails Auto-Configuration: Zero-configuration setup via Railtie
• Rack Middleware: Automatic request instrumentation for any Rack application
• Thread-Safe Metrics: Concurrent metric collection with automatic buffering
• Production-Ready: Comprehensive error handling and graceful shutdown

Add this line to your application's Gemfile:

gem 'tracekit'

And then execute:

bundle install

Or install it yourself as:

gem install tracekit

The SDK automatically configures itself in Rails applications using environment variables:

1. Create .env file:

TRACEKIT_API_KEY=ctxio_abc123...
TRACEKIT_ENDPOINT=app.tracekit.dev
TRACEKIT_SERVICE_NAME=my-rails-app
TRACEKIT_ENVIRONMENT=production
TRACEKIT_CODE_MONITORING=true

2. That's it! The Railtie automatically:

• Loads configuration from ENV variables
• Initializes OpenTelemetry with OTLP exporters
• Adds Rack middleware for request instrumentation
• Sets up graceful shutdown

3. Use the SDK in your controllers:

class CheckoutController < ApplicationController
  def create
    sdk = Tracekit.sdk

    # Capture snapshot with context
    sdk.capture_snapshot("checkout-start", {
      userId: params[:user_id],
      amount: params[:amount]
    })

    # Track metrics
    sdk.counter("checkout.requests").add(1)
    sdk.gauge("checkout.active").set(active_checkouts)

    # Your business logic here...

    sdk.capture_snapshot("checkout-complete", {
      userId: params[:user_id],
      paymentId: payment.id,
      status: "success"
    })

    render json: { status: "success" }
  end
end

For non-Rails applications, manually configure the SDK:

require 'tracekit'

# Configure the SDK
Tracekit.configure do |config|
  config.api_key = ENV['TRACEKIT_API_KEY']
  config.service_name = 'my-service'
  config.endpoint = 'app.tracekit.dev'
  config.environment = 'production'
  config.enable_code_monitoring = true
end

# Use the SDK
sdk = Tracekit.sdk

# Capture snapshots
sdk.capture_snapshot("process-start", {
  jobId: job.id,
  status: "processing"
})

# Track metrics
counter = sdk.counter("jobs.processed", { type: "background" })
counter.add(1)

# At application shutdown
Tracekit.shutdown

For Rack-based frameworks:

require 'tracekit'

Tracekit.configure do |config|
  config.api_key = ENV['TRACEKIT_API_KEY']
  config.service_name = 'my-sinatra-app'
end

# Add middleware
use Tracekit::Middleware

# Your application code...

Tracekit.configure do |config|
  config.api_key = "ctxio_abc123..."              # Required: Your TraceKit API key
  config.service_name = "my-service"              # Required: Service identifier
  config.endpoint = "app.tracekit.dev"            # Optional: TraceKit endpoint
  config.use_ssl = true                           # Optional: Use HTTPS (default: true)
  config.environment = "production"               # Optional: Environment name
  config.service_version = "1.0.0"                # Optional: Service version
  config.enable_code_monitoring = true            # Optional: Enable snapshots
  config.code_monitoring_poll_interval = 30       # Optional: Polling interval (seconds)
  config.local_ui_port = 4000                     # Optional: Local UI port
  config.sampling_rate = 1.0                      # Optional: Trace sampling (0.0-1.0)
end

sdk = Tracekit.sdk

# Create counter with tags
counter = sdk.counter("http.requests.total", {
  service: "api",
  endpoint: "/users"
})

# Increment
counter.add(1)
counter.add(5)  # Add specific value

# Create gauge
gauge = sdk.gauge("memory.usage.bytes")

# Set value
gauge.set(1024 * 1024 * 512)  # 512 MB

# Increment/decrement
gauge.inc      # +1
gauge.inc(10)  # +10
gauge.dec      # -1
gauge.dec(5)   # -5

# Create histogram with tags
histogram = sdk.histogram("http.request.duration", {
  unit: "ms"
})

# Record values
histogram.record(123.45)
histogram.record(67.89)

Metrics are automatically:

• Buffered in memory (up to 100 metrics or 10 seconds)
• Exported in OTLP JSON format
• Batched for efficiency
• Thread-safe for concurrent access

TraceKit enables non-breaking snapshots of your application's runtime state:

sdk = Tracekit.sdk

# Capture snapshot with variable state
sdk.capture_snapshot("checkout-start", {
  userId: 123,
  amount: 99.99,
  cart_items: ["item1", "item2"],
  status: "processing"
})

• Automatic Context Capture: File path, line number, function name extracted automatically
• Security Scanning: PII and credentials automatically detected and redacted
• Trace Correlation: Snapshots linked to active trace_id and span_id
• Auto-Registration: Breakpoints automatically registered on first capture
• Zero Performance Impact: When breakpoints are inactive, snapshots are skipped

The SDK automatically detects and redacts:

PII (Personally Identifiable Information):

• Email addresses
• Social Security Numbers (SSN)
• Credit card numbers
• Phone numbers

Credentials:

• API keys
• AWS access keys
• Stripe keys
• JWT tokens
• Private keys
• Passwords

Example:

sdk.capture_snapshot("user-login", {
  email: "user@example.com",        # Redacted: [REDACTED]
  password: "secret123",             # Redacted: [REDACTED]
  api_key: "sk_live_abc123..."       # Redacted: [REDACTED]
})

The SDK automatically:

• Propagates W3C TraceContext headers (traceparent, tracestate)
• Creates spans for incoming HTTP requests (via middleware)
• Extracts trace context from upstream services
• Exports traces to TraceKit using OTLP/HTTP

The TraceKit Ruby SDK automatically instruments the following components when available:

Web Frameworks:

• Rails - Controller actions, request routing, and lifecycle events
• Rack - HTTP requests/responses with explicit Server span kind
• ActionPack - Controller and request/response processing
• ActionView - Template and view rendering

HTTP Clients:

• Net::HTTP - Standard library HTTP client with automatic trace propagation
• HTTP gem - HTTP gem client library

Databases:

• ActiveRecord - ORM layer operations (creates Internal spans)
• PostgreSQL (PG) - SQL queries with statement, system, and operation attributes (creates Client spans)
• MySQL2 - MySQL database operations

Background Jobs & Cache:

• Redis - Cache operations and data access
• Sidekiq - Background job processing and queues

Important: The SDK's Rack middleware explicitly creates server spans with kind: Server for all incoming HTTP requests, ensuring consistent span classification across all Ruby frameworks (Rails, Sinatra, Grape, etc.).

OpenTelemetry automatically instruments HTTP clients:

require 'net/http'

# Automatically traced - propagates trace context
uri = URI('http://localhost:8080/api/data')
response = Net::HTTP.get_response(uri)

A typical Rails request produces the following span hierarchy:

GET /users (kind: Server) - Root span from Tracekit::Middleware
  ├─ ApplicationController#users (kind: Internal) - Rails controller action
  ├─ User.all (kind: Internal) - ActiveRecord query
  │   └─ SELECT * FROM users (kind: Client) - PostgreSQL query span
  ├─ User.where (kind: Internal) - ActiveRecord query
  │   └─ SELECT * FROM users WHERE... (kind: Client) - PostgreSQL query span
  └─ users/index rendering (kind: Internal) - ActionView template rendering

Span Kinds:

• Server - Incoming HTTP requests (set explicitly by TraceKit middleware)
• Client - Outgoing HTTP requests and database queries
• Internal - Application-level operations (ORM, rendering, etc.)

ruby-sdk/
├── lib/
│   ├── tracekit/
│   │   ├── config.rb              # Configuration with builder pattern
│   │   ├── endpoint_resolver.rb   # URL resolution logic
│   │   ├── sdk.rb                 # Main SDK class
│   │   ├── railtie.rb             # Rails auto-configuration
│   │   ├── middleware.rb          # Rack middleware
│   │   ├── metrics/               # Metrics implementation
│   │   ├── security/              # Security scanning
│   │   └── snapshots/             # Code monitoring
│   └── tracekit.rb                # Entry point
├── spec/                          # RSpec tests
├── ruby-test/                     # Cross-service test app
├── README.md
└── tracekit.gemspec

• Ruby 2.7 or higher
• Bundler
• Git
• TraceKit API key

# Clone the repository
git clone git@github.com:Tracekit-Dev/ruby-sdk.git
cd ruby-sdk

# Install dependencies
bundle install

# Run tests
bundle exec rspec

# Run test application
cd ruby-test
bundle install
cp .env.example .env
# Edit .env with your API key
bundle exec rails server -p 5002

# Run all tests
bundle exec rspec

# Run specific test file
bundle exec rspec spec/tracekit/endpoint_resolver_spec.rb

# Run with coverage
COVERAGE=true bundle exec rspec

The ruby-test/ directory contains a Rails API application for testing cross-service communication:

cd ruby-test
bundle exec rails server -p 5002

Endpoints:

• GET / - Service information
• GET /health - Health check
• GET /test - Code monitoring test
• GET /error-test - Exception test
• GET /checkout - Checkout simulation
• GET /api/call-go - Call Go test service
• GET /api/call-node - Call Node test service
• GET /api/call-all - Call all test services

See ruby-test/README.md for details.

• Ruby: 2.7 or later (tested up to 3.3)
• Rails: 6.0+ (for Rails integration)
• Dependencies:
  • opentelemetry-sdk (~> 1.2)
  • opentelemetry-exporter-otlp (~> 0.26)
  • opentelemetry-instrumentation-all (~> 0.50)
  • concurrent-ruby (~> 1.2)
  • httparty (~> 0.21) (test app only)

• CHANGELOG - Version history and release notes
• TraceKit Documentation
• Test Application README

Ensure your .env file is loaded:

# config/application.rb
require 'dotenv/load' if defined?(Dotenv)

Check that:

1. API key is valid
2. Endpoint is reachable
3. Metrics are being flushed (wait 10 seconds or accumulate 100 metrics)

Verify:

1. TRACEKIT_CODE_MONITORING=true
2. API key has snapshot permissions
3. Breakpoints are registered (check logs)

• Documentation: https://docs.tracekit.dev
• Issues: https://github.com/Tracekit-Dev/ruby-sdk/issues
• Email: support@tracekit.dev

We welcome contributions! To contribute:

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Write tests for your changes
4. Ensure all tests pass (bundle exec rspec)
5. Commit your changes (git commit -m 'Add amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

This project is licensed under the MIT License - see the LICENSE file for details.

Built on OpenTelemetry - the industry standard for observability.

Repository: git@github.com:Tracekit-Dev/ruby-sdk.git Version: v0.1.0