Ruby Integration Guide

# Gemfile
gem 'tracekit'

# Then run:
bundle install

# .env file
TRACEKIT_API_KEY=ctxio_abc123...
TRACEKIT_ENDPOINT=https://app.tracekit.dev
TRACEKIT_SERVICE_NAME=my-rails-app
TRACEKIT_ENVIRONMENT=production
TRACEKIT_CODE_MONITORING=true

# That's it! The TraceKit Railtie automatically:
# - Loads configuration from ENV variables
# - Initializes OpenTelemetry with OTLP exporters
# - Adds Rack middleware for request instrumentation
# - Sets up graceful shutdown

require 'tracekit'

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

# For Rack applications, add middleware
use Tracekit::Middleware

# At application shutdown
at_exit { Tracekit.shutdown }

# Your controllers are automatically traced!
class UsersController < ApplicationController
  def index
    # This action is automatically traced!
    @users = User.all
    render json: @users
  end

  def create
    sdk = Tracekit.sdk

    # Track metrics
    sdk.counter("user.created").add(1)

    # Capture snapshot with context
    sdk.capture_snapshot("user-create", {
      email: params[:email],
      name: params[:name]
    })

    @user = User.create!(user_params)
    render json: @user, status: :created
  end

  private

  def user_params
    params.require(:user).permit(:name, :email)
  end
end

# app.rb
require 'sinatra'
require 'tracekit'

# Configure TraceKit
Tracekit.configure do |config|
  config.api_key = ENV['TRACEKIT_API_KEY']
  config.service_name = 'my-sinatra-app'
  config.endpoint = 'https://app.tracekit.dev'
end

# Add TraceKit middleware
use Tracekit::Middleware

# Routes are automatically traced!
get '/api/users' do
  sdk = Tracekit.sdk

  # Track metrics
  sdk.counter("api.users.requests").add(1)

  content_type :json
  User.all.to_json
end

# ActiveRecord is automatically instrumented by TraceKit

# All queries are automatically traced!
User.all                    # Traced!
User.find(1)               # Traced!
User.where(active: true)   # Traced!
User.create(name: 'Alice') # Traced!

# Net::HTTP is automatically instrumented by TraceKit

require 'net/http'

# All HTTP requests are automatically traced!
uri = URI('https://api.example.com/users')
response = Net::HTTP.get_response(uri)  # Traced!

# Redis operations are automatically traced by TraceKit
redis = Redis.new(host: 'localhost', port: 6379)

redis.set('key', 'value')  # Traced!
redis.get('key')           # Traced!

def process_order(order_id)
  sdk = Tracekit.sdk

  # Capture snapshot at key moments
  sdk.capture_snapshot("order-processing-start", {
    orderId: order_id,
    status: "processing"
  })

  # Track metrics
  sdk.counter("orders.processed").add(1)
  sdk.gauge("orders.active").inc

  # Validation logic here...

  # Track duration
  start_time = Time.now
  result = charge_payment(order_id)
  duration_ms = ((Time.now - start_time) * 1000).round(2)

  sdk.histogram("order.payment.duration").record(duration_ms)

  # Capture completion snapshot
  sdk.capture_snapshot("order-processing-complete", {
    orderId: order_id,
    status: "completed",
    duration: duration_ms
  })

  sdk.gauge("orders.active").dec
end

# After configuration:
Tracekit::SDK.configure(config)

# Access anywhere in your application:
sdk = Tracekit::SDK.current
sdk.capture_snapshot("checkout", { order_id: order.id, total: total })
sdk.counter("orders.processed").inc

# config/initializers/tracekit.rb
Tracekit::SDK.configure do |c|
  c.api_key              = ENV['TRACEKIT_API_KEY']
  c.service_name         = "my-rails-app"
  c.enable_code_monitoring = true  # defaults to true in Ruby SDK
end

# In a Rails controller
class OrdersController < ApplicationController
  def create
    order = Order.new(order_params)
    user  = current_user

    # Instance method -- capture via the SDK singleton
    sdk = Tracekit::SDK.current
    sdk.capture_snapshot('order-create', {
      order_id: order.id,
      total:    order.total,
      user_id:  user.id,
      items:    order.line_items.count
    })

    # Module convenience method -- same result, shorter syntax
    Tracekit.capture_snapshot('order-validate', {
      valid:  order.valid?,
      errors: order.errors.full_messages
    })

    if order.save
      redirect_to order_path(order)
    else
      render :new
    end
  end
end

Tracekit.configure do |c|
  c.api_key = ENV['TRACEKIT_API_KEY']
  c.service_name = 'my-ruby-service'
  c.llm.enabled = true          # Master toggle
  c.llm.openai = true           # OpenAI instrumentation
  c.llm.anthropic = true        # Anthropic instrumentation
  c.llm.capture_content = false # Capture prompts/completions (off by default)
end

# .env
TRACEKIT_API_KEY=ctxio_your_generated_api_key_here
TRACEKIT_ENDPOINT=https://app.tracekit.dev
TRACEKIT_SERVICE_NAME=my-rails-app
TRACEKIT_ENVIRONMENT=production
TRACEKIT_CODE_MONITORING=true

# Complete Rails example with TraceKit SDK

# Gemfile
gem 'tracekit'

# .env
TRACEKIT_API_KEY=ctxio_your_generated_api_key_here
TRACEKIT_ENDPOINT=https://app.tracekit.dev
TRACEKIT_SERVICE_NAME=rails-api
TRACEKIT_ENVIRONMENT=production
TRACEKIT_CODE_MONITORING=true

# app/controllers/users_controller.rb
class UsersController < ApplicationController
  def index
    # Automatically traced - no code changes needed!
    @users = User.all
    render json: @users
  end

  def show
    # Automatically traced - no code changes needed!
    @user = User.find(params[:id])
    render json: @user
  end

  def create
    sdk = Tracekit.sdk

    # Track metrics
    sdk.counter("users.created").add(1)

    # Capture snapshot for debugging
    sdk.capture_snapshot("user-creation", {
      email: params[:email],
      name: params[:name]
    })

    @user = User.create!(user_params)
    render json: @user, status: :created
  end

  private

  def user_params
    params.require(:user).permit(:name, :email)
  end
end

# That's it! Your Rails app now has:
# - Distributed tracing with automatic span creation
# - Metrics collection (counters, gauges, histograms)
# - Code monitoring with non-breaking snapshots

sdk = Tracekit.sdk

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

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

sdk = Tracekit.sdk

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

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

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

sdk = Tracekit.sdk

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

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

require 'opentelemetry/sdk'
require 'opentelemetry-exporter-otlp'

OpenTelemetry::SDK.configure do |c|
  c.service_name = 'my-service'
  c.add_span_processor(
    OpenTelemetry::SDK::Trace::Export::BatchSpanProcessor.new(
      OpenTelemetry::Exporter::OTLP::Exporter.new(
        endpoint: 'https://api.tracekit.io/v1/traces',
        headers: { 'Authorization' => "Bearer #{api_key}" }
      )
    )
  )
  c.use_all # auto-instrumentation
end

# Rails: just set .env vars (auto-configured via Railtie)
# TRACEKIT_API_KEY=your-api-key
# TRACEKIT_SERVICE_NAME=my-service

# Non-Rails:
Tracekit.configure do |c|
  c.api_key = ENV['TRACEKIT_API_KEY']
  c.service_name = 'my-service'
end