tracekit 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: '058e090e61dfe2cb69c18c210dcf53e593f2a5f055e43f178e7a5d58f52f28e6'
+  data.tar.gz: 680249888fb2ae4a22a2e53549c45e6630fe35c9de9d85d8a8011a8fcc5feac2
+SHA512:
+  metadata.gz: 1b1ab7651b55e88f4f53dd82c9634fea099937c4b66e2c0707474942ae6505b07ba1ff2a0be1b4707e776cfba85840b1c3de86810aa57e39925e0a801fa946d9
+  data.tar.gz: 2fcdbc362f4176c6907d9dc4c0089f79548d738e739248657b0c8274fe57ca020199b7d39a047bae5a6846ca842a0a8c6f549f1001cec6dfbd9d729b534a21a6

data/CHANGELOG.md

@@ -0,0 +1,138 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2024-02-04
+
+### Added
+
+- Initial release of TraceKit Ruby SDK
+- OpenTelemetry-based distributed tracing with W3C TraceContext propagation
+- Metrics API with Counter, Gauge, and Histogram support
+- Automatic metrics buffering (100 metrics or 10 seconds)
+- OTLP/HTTP export for traces and metrics
+- Code monitoring with snapshot capture and auto-registration
+- Security scanning for PII and credentials with automatic redaction
+- Local UI auto-detection for development workflows
+- Rails integration via Railtie with automatic configuration
+- Rack middleware for request instrumentation
+- Thread-safe metrics collection using concurrent-ruby
+- Comprehensive test suite with RSpec
+- Cross-service test application (ruby-test) on port 5002
+- Builder pattern configuration with fluent API
+- Endpoint resolution logic matching SDK specification
+- Graceful shutdown with resource cleanup
+- Ruby 2.7+ support
+
+### Features
+
+#### Configuration
+- Environment variable-based configuration for Rails
+- Manual configuration for vanilla Ruby applications
+- Configurable sampling rate (0.0 - 1.0)
+- Configurable code monitoring poll interval
+- SSL/TLS support with configurable endpoint
+
+#### Distributed Tracing
+- Automatic HTTP request/response tracing
+- W3C TraceContext header propagation
+- OpenTelemetry auto-instrumentation for common libraries
+- Trace correlation with code monitoring snapshots
+
+#### Metrics
+- Counter: Monotonic increasing values
+- Gauge: Point-in-time values with inc/dec/set operations
+- Histogram: Value distribution recording
+- Tag support for dimensional metrics
+- Automatic buffering and batch export
+- Thread-safe concurrent collection
+
+#### Code Monitoring
+- Non-breaking snapshot capture
+- Automatic file/line/function context extraction
+- Variable state capture with security scanning
+- Breakpoint auto-registration
+- Polling-based activation check (30-second interval)
+- Trace correlation (trace_id, span_id)
+- Zero performance impact when breakpoints inactive
+
+#### Security
+- PII detection: email, SSN, credit card, phone numbers
+- Credential detection: API keys, AWS keys, Stripe keys, JWT, private keys, passwords
+- Automatic redaction with security flags
+- Variable-level scanning
+
+#### Rails Integration
+- Automatic Railtie configuration
+- ENV-based configuration loading
+- Automatic middleware insertion
+- Graceful shutdown on Rails exit
+- Zero-configuration setup
+
+#### Rack Integration
+- Request/response instrumentation
+- Automatic metric tracking:
+  - `http.server.requests` (counter)
+  - `http.server.active_requests` (gauge)
+  - `http.server.request.duration` (histogram)
+- Client IP extraction from headers
+- OpenTelemetry span enrichment
+
+### Dependencies
+
+- opentelemetry-sdk ~> 1.2
+- opentelemetry-exporter-otlp ~> 0.26
+- opentelemetry-instrumentation-all ~> 0.50
+- concurrent-ruby ~> 1.2
+
+### Test Application
+
+- Rails 7 API-only application
+- Standard test endpoints for cross-service communication
+- HTTParty for HTTP client testing
+- Port 5002 (as per SDK specification)
+- Environment variable configuration
+- Example usage of all SDK features
+
+### Documentation
+
+- Comprehensive README with quick start guide
+- API documentation with code examples
+- Configuration reference
+- Test application setup guide
+- MIT License
+
+---
+
+## Release Notes
+
+### v0.1.0 - Initial Release
+
+This is the first production-ready release of the TraceKit Ruby SDK. It provides complete feature parity with other TraceKit SDKs, including distributed tracing, metrics, and code monitoring.
+
+**Key Highlights**:
+
+1. **Rails-First Design**: Automatic configuration via Railtie makes Rails integration zero-configuration
+2. **OpenTelemetry Native**: Built on industry-standard OpenTelemetry for maximum compatibility
+3. **Thread-Safe**: Uses concurrent-ruby for safe metric collection in multi-threaded applications
+4. **Security Built-In**: Automatic PII and credential detection prevents accidental data exposure
+5. **Production-Ready**: Comprehensive error handling, graceful shutdown, and resource cleanup
+
+**Tested With**:
+- Ruby 2.7, 3.0, 3.1, 3.2, 3.3
+- Rails 6.0, 6.1, 7.0, 7.1
+- Sinatra 3.0+
+- Rack 2.2+
+
+**Breaking Changes**: None (initial release)
+
+**Migration Guide**: Not applicable (initial release)
+
+**Known Issues**: None
+
+---
+
+[0.1.0]: https://github.com/Tracekit-Dev/ruby-sdk/releases/tag/v0.1.0

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 TraceKit
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,509 @@
+# TraceKit Ruby SDK
+
+[![Gem Version](https://img.shields.io/gem/v/tracekit.svg)](https://rubygems.org/gems/tracekit)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Ruby](https://img.shields.io/badge/Ruby-2.7+-red.svg)](https://www.ruby-lang.org/)
+
+Official Ruby SDK for TraceKit APM - OpenTelemetry-based distributed tracing, metrics collection, and application performance monitoring for Ruby applications.
+
+## Status
+
+The SDK is production-ready with full support for distributed tracing, metrics, and code monitoring.
+
+## Overview
+
+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.
+
+## Features
+
+- **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
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'tracekit'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself as:
+
+```bash
+gem install tracekit
+```
+
+## Quick Start
+
+### Rails Applications
+
+The SDK automatically configures itself in Rails applications using environment variables:
+
+**1. Create `.env` file:**
+
+```bash
+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:**
+
+```ruby
+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
+```
+
+### Vanilla Ruby Applications
+
+For non-Rails applications, manually configure the SDK:
+
+```ruby
+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
+```
+
+### Rack Middleware (Sinatra, Grape, etc.)
+
+For Rack-based frameworks:
+
+```ruby
+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...
+```
+
+## Configuration Options
+
+```ruby
+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
+```
+
+### Environment Variables (Rails Auto-Configuration)
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `TRACEKIT_API_KEY` | Your TraceKit API key (required) | - |
+| `TRACEKIT_SERVICE_NAME` | Service identifier | - |
+| `TRACEKIT_ENDPOINT` | TraceKit endpoint | `app.tracekit.dev` |
+| `TRACEKIT_ENVIRONMENT` | Environment name | `development` |
+| `TRACEKIT_CODE_MONITORING` | Enable code monitoring | `true` |
+| `TRACEKIT_SAMPLING_RATE` | Trace sampling rate | `1.0` |
+
+## Metrics API
+
+### Counter (Monotonic)
+
+```ruby
+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
+```
+
+### Gauge (Point-in-Time Values)
+
+```ruby
+# 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
+```
+
+### Histogram (Distributions)
+
+```ruby
+# Create histogram with tags
+histogram = sdk.histogram("http.request.duration", {
+  unit: "ms"
+})
+
+# Record values
+histogram.record(123.45)
+histogram.record(67.89)
+```
+
+### Automatic Buffering
+
+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
+
+## Code Monitoring
+
+TraceKit enables non-breaking snapshots of your application's runtime state:
+
+```ruby
+sdk = Tracekit.sdk
+
+# Capture snapshot with variable state
+sdk.capture_snapshot("checkout-start", {
+  userId: 123,
+  amount: 99.99,
+  cart_items: ["item1", "item2"],
+  status: "processing"
+})
+```
+
+### Features
+
+- **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
+
+### Security Detection
+
+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:
+```ruby
+sdk.capture_snapshot("user-login", {
+  email: "user@example.com",        # Redacted: [REDACTED]
+  password: "secret123",             # Redacted: [REDACTED]
+  api_key: "sk_live_abc123..."       # Redacted: [REDACTED]
+})
+```
+
+## Distributed Tracing
+
+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
+
+### Auto-Instrumentation
+
+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.).
+
+### HTTP Client Instrumentation
+
+OpenTelemetry automatically instruments HTTP clients:
+
+```ruby
+require 'net/http'
+
+# Automatically traced - propagates trace context
+uri = URI('http://localhost:8080/api/data')
+response = Net::HTTP.get_response(uri)
+```
+
+### Span Hierarchy Example
+
+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.)
+
+## Project Structure
+
+```
+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
+```
+
+## Development Setup
+
+### Prerequisites
+
+- Ruby 2.7 or higher
+- Bundler
+- Git
+- TraceKit API key
+
+### Building from Source
+
+```bash
+# 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
+```
+
+### Running Tests
+
+```bash
+# 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
+```
+
+## Test Application
+
+The `ruby-test/` directory contains a Rails API application for testing cross-service communication:
+
+```bash
+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](ruby-test/README.md) for details.
+
+## Requirements
+
+- **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)
+
+## Documentation
+
+- [CHANGELOG](CHANGELOG.md) - Version history and release notes
+- [TraceKit Documentation](https://app.tracekit.dev/docs)
+- [Test Application README](ruby-test/README.md)
+
+## Troubleshooting
+
+### Rails not auto-configuring
+
+Ensure your `.env` file is loaded:
+
+```ruby
+# config/application.rb
+require 'dotenv/load' if defined?(Dotenv)
+```
+
+### Metrics not appearing
+
+Check that:
+1. API key is valid
+2. Endpoint is reachable
+3. Metrics are being flushed (wait 10 seconds or accumulate 100 metrics)
+
+### Snapshots not capturing
+
+Verify:
+1. `TRACEKIT_CODE_MONITORING=true`
+2. API key has snapshot permissions
+3. Breakpoints are registered (check logs)
+
+## Support
+
+- **Documentation**: https://docs.tracekit.dev
+- **Issues**: https://github.com/Tracekit-Dev/ruby-sdk/issues
+- **Email**: support@tracekit.dev
+
+## Contributing
+
+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
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Acknowledgments
+
+Built on [OpenTelemetry](https://opentelemetry.io/) - the industry standard for observability.
+
+---
+
+**Repository**: git@github.com:Tracekit-Dev/ruby-sdk.git
+**Version**: v0.1.0