diff --git a/example/otel/README.md b/example/otel/README.md index f948f91be..8db4667b0 100644 --- a/example/otel/README.md +++ b/example/otel/README.md @@ -1,59 +1,124 @@ -# Example for go-redis OpenTelemetry instrumentation +# go-redis OpenTelemetry Monitoring with Uptrace -This example demonstrates how to monitor Redis using OpenTelemetry and -[Uptrace](https://github.com/uptrace/uptrace). It requires Docker to start Redis Server and Uptrace. +This example demonstrates how to instrument and monitor Redis operations in Go applications using +OpenTelemetry and [Uptrace](https://github.com/uptrace/uptrace), providing comprehensive +observability into your Redis performance and operations. -See -[Monitoring Go Redis Performance and Errors](https://redis.uptrace.dev/guide/go-redis-monitoring.html) -for details. +## Overview -**Step 1**. Download the example using Git: +This integration provides: -```shell +- **Distributed tracing** for Redis operations +- **Performance monitoring** with latency and throughput metrics +- **Error tracking** and debugging capabilities +- **Visual dashboards** for Redis health monitoring +- **Production-ready** observability stack with Docker + +## Prerequisites + +- Go 1.19+ +- Docker and Docker Compose +- Basic understanding of Redis and OpenTelemetry + +## Quick Start + +### 1. Clone and Navigate + +```bash git clone https://github.com/redis/go-redis.git cd example/otel ``` -**Step 2**. Start the services using Docker: +### 2. Start the Monitoring Stack + +Launch Redis and Uptrace services: -```shell -docker-compose up -d +```bash +docker compose up -d ``` -**Step 3**. Make sure Uptrace is running: +This starts: + +- Redis server on `localhost:6379` +- Uptrace APM on `http://localhost:14318` -```shell -docker-compose logs uptrace +### 3. Verify Services + +Check that Uptrace is running properly: + +```bash +docker compose logs uptrace ``` -**Step 4**. Run the Redis client example and Follow the link to view the trace: +Look for successful startup messages without errors. + +### 4. Run the Example + +Execute the instrumented Redis client: -```shell +```bash go run client.go +``` + +You should see output similar to: + +``` trace: http://localhost:14318/traces/ee029d8782242c8ed38b16d961093b35 ``` -![Redis trace](./image/redis-trace.png) +Click the trace URL to view detailed operation traces in Uptrace. + +![Redis trace visualization](./image/redis-trace.png) + +### 5. Explore the Dashboard + +Open the Uptrace UI at [http://localhost:14318](http://localhost:14318/metrics/1) to explore: + +- **Traces**: Individual Redis operation details +- **Metrics**: Performance statistics and trends +- **Logs**: Application and system logs +- **Service Map**: Visual representation of dependencies + +## Advanced Monitoring Setup + +### Redis Performance Metrics -You can also open Uptrace UI at [http://localhost:14318](http://localhost:14318) to view available -spans, logs, and metrics. +For production environments, enable comprehensive Redis monitoring by installing the OpenTelemetry +Collector: -## Redis monitoring +The [OpenTelemetry Collector](https://uptrace.dev/opentelemetry/collector) acts as a telemetry agent +that: -You can also [monitor Redis performance](https://uptrace.dev/opentelemetry/redis-monitoring.html) -metrics By installing OpenTelemetry Collector. +- Pulls performance metrics directly from Redis +- Collects system-level statistics +- Forwards data to Uptrace via OTLP protocol -[OpenTelemetry Collector](https://uptrace.dev/opentelemetry/collector.html) is an agent that pulls -telemetry data from systems you want to monitor and sends it to APM tools using the OpenTelemetry -protocol (OTLP). +When configured, Uptrace automatically generates a Redis dashboard: -When telemetry data reaches Uptrace, it automatically generates a Redis dashboard from a pre-defined -template. +![Redis performance dashboard](./image/metrics.png) -![Redis dashboard](./image/metrics.png) +### Key Metrics Monitored + +- **Connection Statistics**: Active connections, connection pool utilization +- **Command Performance**: Operation latency, throughput, error rates +- **Memory Usage**: Memory consumption, key distribution +- **Replication Health**: Master-slave sync status and lag + +### Logs and Debugging + +View service logs: + +```bash +# All services +docker compose logs + +# Specific service +docker compose logs redis +docker compose logs uptrace +``` -## Links +## Additional Resources -- [Uptrace open-source APM](https://uptrace.dev/get/open-source-apm.html) -- [OpenTelemetry Go instrumentations](https://uptrace.dev/opentelemetry/instrumentations/?lang=go) -- [OpenTelemetry Go Tracing API](https://uptrace.dev/opentelemetry/go-tracing.html) +- [Complete go-redis Monitoring Guide](https://redis.uptrace.dev/guide/go-redis-monitoring.html) +- [OpenTelemetry Go Instrumentation](https://uptrace.dev/get/opentelemetry-go/tracing) +- [Uptrace Open Source APM](https://uptrace.dev/get/hosted/open-source-apm) diff --git a/example/otel/client.go b/example/otel/client.go index 984d83f09..165a9234a 100644 --- a/example/otel/client.go +++ b/example/otel/client.go @@ -7,10 +7,11 @@ import ( "sync" "time" - "github.com/uptrace/uptrace-go/uptrace" "go.opentelemetry.io/otel" "go.opentelemetry.io/otel/codes" + "github.com/uptrace/uptrace-go/uptrace" + "github.com/redis/go-redis/extra/redisotel/v9" "github.com/redis/go-redis/v9" ) @@ -22,7 +23,7 @@ func main() { uptrace.ConfigureOpentelemetry( // copy your project DSN here or use UPTRACE_DSN env var - uptrace.WithDSN("http://project2_secret_token@localhost:14317/2"), + uptrace.WithDSN("http://project1_secret@localhost:14318/2?grpc=14317"), uptrace.WithServiceName("myservice"), uptrace.WithServiceVersion("v1.0.0"), diff --git a/example/otel/config/otel-collector.yaml b/example/otel/config/otel-collector.yaml index 2cb130dd6..6d79694eb 100644 --- a/example/otel/config/otel-collector.yaml +++ b/example/otel/config/otel-collector.yaml @@ -23,9 +23,15 @@ receivers: redis: endpoint: 'redis-server:6379' collection_interval: 10s - jaeger: - protocols: - grpc: + postgresql: + endpoint: postgres:5432 + transport: tcp + username: uptrace + password: uptrace + databases: + - uptrace + tls: + insecure: true processors: resourcedetection: @@ -37,10 +43,10 @@ processors: exporters: otlp/uptrace: - endpoint: http://uptrace:14317 + endpoint: http://uptrace:4317 tls: insecure: true - headers: { 'uptrace-dsn': 'http://project2_secret_token@localhost:14317/2' } + headers: { 'uptrace-dsn': 'http://project1_secret@localhost:14318/2?grpc=14317' } debug: service: @@ -49,7 +55,7 @@ service: # level: DEBUG pipelines: traces: - receivers: [otlp, jaeger] + receivers: [otlp] processors: [batch] exporters: [otlp/uptrace] metrics: @@ -57,7 +63,7 @@ service: processors: [cumulativetodelta, batch] exporters: [otlp/uptrace] metrics/hostmetrics: - receivers: [hostmetrics, redis] + receivers: [hostmetrics, redis, postgresql] processors: [cumulativetodelta, batch, resourcedetection] exporters: [otlp/uptrace] logs: diff --git a/example/otel/docker-compose.yml b/example/otel/docker-compose.yml index 4244792a9..021f5658c 100644 --- a/example/otel/docker-compose.yml +++ b/example/otel/docker-compose.yml @@ -1,10 +1,10 @@ -version: '3' - services: clickhouse: - image: clickhouse/clickhouse-server:23.7 + image: clickhouse/clickhouse-server:25.3.5 restart: on-failure environment: + CLICKHOUSE_USER: uptrace + CLICKHOUSE_PASSWORD: uptrace CLICKHOUSE_DB: uptrace healthcheck: test: ['CMD', 'wget', '--spider', '-q', 'localhost:8123/ping'] @@ -12,13 +12,13 @@ services: timeout: 1s retries: 30 volumes: - - ch_data2:/var/lib/clickhouse + - ch_data:/var/lib/clickhouse ports: - '8123:8123' - '9000:9000' postgres: - image: postgres:15-alpine + image: postgres:17-alpine restart: on-failure environment: PGDATA: /var/lib/postgresql/data/pgdata @@ -31,27 +31,27 @@ services: timeout: 1s retries: 30 volumes: - - 'pg_data2:/var/lib/postgresql/data/pgdata' + - 'pg_data:/var/lib/postgresql/data/pgdata' ports: - '5432:5432' uptrace: - image: 'uptrace/uptrace:1.6.2' + image: 'uptrace/uptrace:2.0.0' #image: 'uptrace/uptrace-dev:latest' restart: on-failure volumes: - - ./uptrace.yml:/etc/uptrace/uptrace.yml + - ./uptrace.yml:/etc/uptrace/config.yml #environment: # - DEBUG=2 ports: - - '14317:14317' - - '14318:14318' + - '14317:4317' + - '14318:80' depends_on: clickhouse: condition: service_healthy otelcol: - image: otel/opentelemetry-collector-contrib:0.91.0 + image: otel/opentelemetry-collector-contrib:0.123.0 restart: on-failure volumes: - ./config/otel-collector.yaml:/etc/otelcol-contrib/config.yaml @@ -64,11 +64,19 @@ services: volumes: - ./config/vector.toml:/etc/vector/vector.toml:ro - mailhog: - image: mailhog/mailhog:v1.0.1 - restart: on-failure + mailpit: + image: axllent/mailpit + restart: always ports: - - '8025:8025' + - 1025:1025 + - 8025:8025 + environment: + MP_MAX_MESSAGES: 5000 + MP_DATA_FILE: /data/mailpit.db + MP_SMTP_AUTH_ACCEPT_ANY: 1 + MP_SMTP_AUTH_ALLOW_INSECURE: 1 + volumes: + - mailpit_data:/data redis-server: image: redis @@ -78,5 +86,6 @@ services: image: redis volumes: - ch_data2: - pg_data2: + ch_data: + pg_data: + mailpit_data: diff --git a/example/otel/image/metrics.png b/example/otel/image/metrics.png index 7c2beb4d6..899ae64b4 100644 Binary files a/example/otel/image/metrics.png and b/example/otel/image/metrics.png differ diff --git a/example/otel/image/redis-trace.png b/example/otel/image/redis-trace.png index 4f7115e1c..fb31d2e8b 100644 Binary files a/example/otel/image/redis-trace.png and b/example/otel/image/redis-trace.png differ diff --git a/example/otel/uptrace.yml b/example/otel/uptrace.yml index 90ecbf750..35cb73306 100644 --- a/example/otel/uptrace.yml +++ b/example/otel/uptrace.yml @@ -1,265 +1,426 @@ -## -## Uptrace configuration file. -## See https://uptrace.dev/get/config.html for details. -## -## You can use environment variables anywhere in this file, for example: -## -## foo: $FOO -## bar: ${BAR} -## baz: ${BAZ:default} -## -## To escape `$`, use `$$`, for example: -## -## foo: $$FOO_BAR -## - -## -## ClickHouse database credentials. -## -ch: - addr: clickhouse:9000 - user: default - password: - database: uptrace - - # Maximum query execution time. - max_execution_time: 30s - - # TLS configuration. Uncomment to enable. - # tls: - # insecure_skip_verify: true - - # TLS configuration. Uncomment to enable. - # tls: - # insecure_skip_verify: true # only for self-signed certificates - -## -## PostgreSQL db that is used to store metadata such us metric names, dashboards, alerts, -## and so on. -## -pg: - addr: postgres:5432 - user: uptrace - password: uptrace - database: uptrace - -## -## A list of pre-configured projects. Each project is fully isolated. -## -projects: - # Conventionally, the first project is used to monitor Uptrace itself. - - id: 1 - name: Uptrace - # Token grants write access to the project. Keep a secret. - token: project1_secret_token - pinned_attrs: - - service_name - - host_name - - deployment_environment - # Group spans by deployment.environment attribute. - group_by_env: false - # Group funcs spans by service.name attribute. - group_funcs_by_service: false - # Enable prom_compat if you want to use the project as a Prometheus datasource in Grafana. - prom_compat: true - - # Other projects can be used to monitor your applications. - # To monitor micro-services or multiple related services, use a single project. - - id: 2 - name: My project - token: project2_secret_token - pinned_attrs: - - service_name - - host_name - - deployment_environment - group_by_env: false - group_funcs_by_service: false - prom_compat: true - -## -## Create metrics from spans and events. -## -metrics_from_spans: - - name: uptrace.tracing.spans - description: Spans duration (excluding events) - instrument: histogram - unit: microseconds - value: _duration / 1000 - attrs: - - _system - - _group_id - - service_name - - host_name - - _status_code - annotations: - - display_name - where: _event_name = '' - - - name: uptrace.tracing.events - description: Events count (excluding spans) - instrument: counter - unit: 1 - value: _count - attrs: - - _system - - _group_id - - _name - - host_name - annotations: - - display_name - where: _is_event = 1 - -## -## To require authentication, uncomment one of the following sections. -## +# ============================================================================= +# Uptrace Configuration +# ============================================================================= +# Complete configuration reference: https://uptrace.dev/get/hosted/config +# +# Environment Variable Support: +# - Simple substitution: foo: $FOO +# - With braces: bar: ${BAR} +# - With defaults: baz: ${BAZ:default_value} +# - To escape '$': foo: $$FOO_BAR +# ============================================================================= + +# ----------------------------------------------------------------------------- +# Service Configuration +# ----------------------------------------------------------------------------- +# Core service settings that define the runtime environment and security +service: + env: hosted # Environment: hosted, development, production + secret: FIXME # Secret key for cryptographic operations (CHANGE THIS!) + +# ----------------------------------------------------------------------------- +# Site Configuration +# ----------------------------------------------------------------------------- +# External-facing URLs and endpoints for client connections +site: + # Primary URL where users access the Uptrace UI and API + # This URL is used for: + # - Generating dashboard links in notifications + # - CORS validation for browser requests + # - Redirect URIs for authentication flows + # IMPORTANT: Must be accessible from all clients and match your reverse proxy setup + url: http://localhost:14318 + + # Dedicated URL for telemetry data ingestion (OTLP endpoints) + # Use this to separate data ingestion from UI traffic for: + # - Load balancing optimization + # - Different security policies + # - CDN/edge deployment scenarios + # If empty, defaults to site.url + ingest_url: http://localhost:14318?grpc=14317 + +# ----------------------------------------------------------------------------- +# Network Listeners +# ----------------------------------------------------------------------------- +# Configure network interfaces and ports for different protocols +listen: + # HTTP server configuration + # Handles: OTLP/HTTP API, REST API, and Vue.js web interface + http: + # Network address and port to bind to + # Format: [host]:port or :port (binds to all interfaces) + # Common values: :80, :8080, localhost:8080 + addr: :80 + + # gRPC server configuration + # Handles: OTLP/gRPC API for high-performance telemetry ingestion + # Standard OTLP gRPC port is 4317 + grpc: + addr: :4317 + + # TLS/SSL configuration for HTTPS and secure gRPC + # Uncomment and configure for production deployments + #tls: + # cert_file: /etc/uptrace/server.crt + # key_file: /etc/uptrace/server.key + +# ----------------------------------------------------------------------------- +# Authentication & Authorization +# ----------------------------------------------------------------------------- +# User authentication and access control settings auth: - users: - - name: Anonymous - email: uptrace@localhost - password: uptrace - notify_by_email: true - - # Cloudflare Zero Trust Access (Identity) - # See https://developers.cloudflare.com/cloudflare-one/identity/ for more info. - # cloudflare: - # # The base URL of the Cloudflare Zero Trust team. - # - team_url: https://myteam.cloudflareaccess.com - # # The Application Audience (AUD) Tag for this application. - # # You can retrieve this from the Cloudflare Zero Trust 'Access' Dashboard. - # audience: bea6df23b944e4a0cd178609ba1bb64dc98dfe1f66ae7b918e563f6cf28b37e0 - - # OpenID Connect (Single Sign-On) - oidc: - # # The ID is used in API endpoints, for example, in redirect URL - # # `http:///api/v1/sso//callback`. - # - id: keycloak - # # Display name for the button in the login form. - # # Default to 'OpenID Connect' - # display_name: Keycloak - # # The base URL for the OIDC provider. - # issuer_url: http://localhost:8080/realms/uptrace - # # The OAuth 2.0 Client ID - # client_id: uptrace - # # The OAuth 2.0 Client Secret - # client_secret: ogbhd8Q0X0e5AZFGSG3m9oirPvnetqkA - # # Additional OAuth 2.0 scopes to request from the OIDC provider. - # # Defaults to 'profile'. 'openid' is requested by default and need not be specified. - # scopes: - # - profile - -## -## Various options to tweak ClickHouse schema. -## For changes to take effect, you need reset the ClickHouse database with `ch reset`. -## -ch_schema: - # Compression codec, for example, LZ4, ZSTD(3), or Default. - compression: ZSTD(3) + # Disable built-in username/password authentication + # Useful when using only SSO providers (OAuth, SAML, etc.) + # Note: SSO authentication methods will remain available + #disabled: true - # Whether to use ReplicatedMergeTree instead of MergeTree. + # Email domain restriction for user registration + # Only users with email addresses matching this regex can register/login + # Examples: + # - '^.+@example\.com$' - only @example.com domain + # - '^.+@(example|acme)\.com$' - multiple domains + # - '^[^@]+@example\.com$' - stricter validation + #email_regexp: '^.+@example\.com$' + +# ----------------------------------------------------------------------------- +# Bootstrap Data +# ----------------------------------------------------------------------------- +# Initial data created during first startup - defines default users, organizations, and projects +# This data is only created once and can be modified through the UI afterward +seed_data: + # Default users created on first startup + users: + - key: user1 # Internal reference key (used in relationships below) + name: Admin # Display name in UI + email: admin@uptrace.local # Login email (must be unique) + password: admin # Plain text password (CHANGE THIS IMMEDIATELY!) + email_confirmed: true + + # API tokens for user authentication + # These tokens can be used for API access and programmatic operations + user_tokens: + - key: user_token1 # Internal reference key + user_key: user1 # References user.key above + token: user1_secret # API token value (CHANGE THIS!) + + # Organizations for multi-tenant deployments + # Organizations group users and projects together + orgs: + - key: org1 # Internal reference key + name: Org1 # Organization display name + + # Organization membership and roles + # Defines which users belong to which organizations + org_users: + - key: org_user1 # Internal reference key + org_key: org1 # References org.key above + user_key: user1 # References user.key above + role: owner # Role: owner, admin, or member + + # Projects contain telemetry data and are isolated from each other + # Each project has its own spans, logs, metrics, and dashboards + projects: + - key: project1 # Internal reference key + name: Project1 # Project display name + org_key: org1 # References org.key above + + # Project-specific tokens for telemetry data ingestion + # These tokens are used in OTLP DSN strings for sending data + project_tokens: + - key: project_token1 # Internal reference key + project_key: project1 # References project.key above + token: project1_secret # Token value for DSN (CHANGE THIS!) + + # Project user permissions + # Controls who can access and modify project data + project_users: + - key: project_user1 # Internal reference key + project_key: project1 # References project.key above + org_user_key: org_user1 # References org_user.key above + perm_level: admin # Permission level: admin, editor, or viewer + +# ----------------------------------------------------------------------------- +# ClickHouse Database Configuration +# ----------------------------------------------------------------------------- +# Primary storage for high-volume telemetry data (spans, logs, metrics) +# ClickHouse is optimized for analytical queries and time-series data +ch_cluster: + # Cluster name for ClickHouse operations + # Used internally for distributed queries and table management + cluster: uptrace1 + + # Enable ClickHouse replicated tables for high availability + # Requires cluster configuration with multiple replicas + # Provides automatic failover and data redundancy replicated: false - # Cluster name for Distributed tables and ON CLUSTER clause. - #cluster: uptrace1 - - spans: - # Delete spans data after 30 days. - ttl_delete: 7 DAY - storage_policy: 'default' - - metrics: - # Delete metrics data after 90 days. - ttl_delete: 30 DAY - storage_policy: 'default' - -## -## Addresses on which Uptrace receives gRPC and HTTP requests. -## -listen: - # OTLP/gRPC API. - grpc: - addr: ':14317' - - # OTLP/HTTP API and Uptrace API with UI. - http: - addr: ':14318' + # Enable ClickHouse distributed tables for horizontal scaling + # Requires cluster configuration across multiple shards + # Only available in Premium Edition + distributed: false + + # Database shards configuration + # Each shard can have multiple replicas for redundancy + shards: + - replicas: + - addr: clickhouse:9000 # ClickHouse server address + database: uptrace # Database name (must exist) + user: uptrace # Database user with write permissions + password: uptrace # Database password + + # Connection timeout settings + dial_timeout: 3s # Time to wait for connection establishment + write_timeout: 5s # Time to wait for write operations + max_retries: 3 # Number of retry attempts for failed operations + + # Query execution timeout + # Prevents long-running queries from consuming resources + max_execution_time: 15s + + # TLS configuration for secure database connections + # Uncomment for production deployments with SSL/TLS + #tls: + # insecure_skip_verify: true # WARNING: Only use for self-signed certificates + +# ----------------------------------------------------------------------------- +# PostgreSQL Database Configuration +# ----------------------------------------------------------------------------- +# Metadata storage for application data (users, projects, dashboards, alerts, etc.) +# PostgreSQL provides ACID compliance for critical application state +pg: + addr: postgres:5432 # PostgreSQL server address + user: uptrace # Database user with full permissions + password: uptrace # Database password + database: uptrace # Database name (must exist) + + # TLS configuration for secure database connections + # Recommended for production deployments + #tls: + # insecure_skip_verify: true # WARNING: Only use for self-signed certificates + +# ----------------------------------------------------------------------------- +# ClickHouse Schema Configuration +# ----------------------------------------------------------------------------- +# Advanced schema settings for performance optimization +# WARNING: Changes require 'ch reset' command and will delete all data +ch_schema: + # Data compression algorithm for storage efficiency + # Options: + # - LZ4: Fast compression/decompression, moderate compression ratio + # - ZSTD(1): Better compression ratio, slightly slower + # - Default: ClickHouse default compression + compression: ZSTD(1) + + # Storage policies for different data types + # Allows using different storage tiers (SSD, HDD, S3) for different data + spans_index: { storage_policy: default } # Span search indexes + spans_data: { storage_policy: default } # Raw span data + span_links: { storage_policy: default } # Span relationship data + logs_index: { storage_policy: default } # Log search indexes + logs_data: { storage_policy: default } # Raw log data + events_index: { storage_policy: default } # Event search indexes + events_data: { storage_policy: default } # Raw event data + metrics: { storage_policy: default } # Metrics time-series data + +# ----------------------------------------------------------------------------- +# Redis Cache Configuration +# ----------------------------------------------------------------------------- +# In-memory cache for improved query performance and session storage +# Reduces database load and improves response times +redis_cache: + # Redis server addresses + # For cluster setup, add multiple addresses + addrs: + 1: redis-server:6379 + + # Redis authentication credentials + username: "" # Redis username (Redis 6.0+) + password: "" # Redis password + db: 0 # Redis database number (0-15) + + # TLS configuration for secure Redis connections + # Recommended for production deployments + #tls: + # insecure_skip_verify: true # WARNING: Only use for self-signed certificates + +# ----------------------------------------------------------------------------- +# SSL/TLS Certificate Management +# ----------------------------------------------------------------------------- +# Automatic certificate issuance and renewal via Let's Encrypt ACME protocol +certmagic: + enabled: false # Enable automatic certificate management + staging_ca: false # Use Let's Encrypt staging environment for testing + http_challenge_addr: :80 # Address for HTTP-01 challenge validation + +# ----------------------------------------------------------------------------- +# Email Configuration +# ----------------------------------------------------------------------------- +# SMTP configuration for alert notifications and user management emails +# Required for: password resets, alert notifications, user invitations +# Documentation: https://uptrace.dev/features/alerting +mailer: + smtp: + enabled: false # Enable email notifications + host: localhost # SMTP server hostname + port: 1025 # SMTP server port (25, 465, 587, 1025) + username: mailhog # SMTP authentication username + password: mailhog # SMTP authentication password + from: no-reply@uptrace.local # Sender email address (must be authorized) + + # TLS configuration + # Most production SMTP servers require TLS + #tls: { insecure: true } # Uncomment to disable opportunistic TLS + +# ----------------------------------------------------------------------------- +# Telemetry Data Processing Configuration +# ----------------------------------------------------------------------------- +# Performance tuning for different types of telemetry data ingestion + +# Spans (distributed tracing data) +# Contains trace information showing request flow across services +spans: + # Number of parallel processing threads + # Default: GOMAXPROCS (number of CPU cores) + # Increase for high-volume tracing workloads + #max_threads: 10 + + # Batch size for database insertions + # Larger batches improve throughput but increase memory usage + # Tune based on your ingestion rate and memory constraints + #max_insert_size: 10000 + + # In-memory buffer capacity for incoming spans + # Spans are dropped when buffer is full (check metrics for drops) + # Default scales with max_threads + #max_buffered_records: 100e3 + +# Span links (relationships between spans) +# Used for connecting spans across trace boundaries +span_links: + # Uncomment to disable span link processing + # This saves resources if you don't use span links + #disabled: true - # tls: - # cert_file: config/tls/uptrace.crt - # key_file: config/tls/uptrace.key + #max_threads: 10 # Processing parallelism + #max_insert_size: 10000 # Batch size for insertions + #max_buffered_records: 100e3 # Buffer capacity + +# Application logs +# Structured and unstructured log data from applications +logs: + #max_threads: 10 # Processing parallelism + #max_insert_size: 10000 # Batch size for insertions + #max_buffered_records: 100e3 # Buffer capacity + +# Custom events +# Application-specific events and business metrics +events: + #max_threads: 10 # Processing parallelism + #max_insert_size: 10000 # Batch size for insertions + #max_buffered_records: 100e3 # Buffer capacity + +# Metrics and time series data +# Numerical measurements over time (counters, gauges, histograms) +metrics: + #max_threads: 10 # Processing parallelism + #max_insert_size: 10000 # Batch size for insertions + #max_buffered_records: 100e3 # Buffer capacity + + # Memory limit for cumulative to delta conversion + # Affects processing of cumulative counters from OpenTelemetry + #max_cumulative_timeseries: 1e6 + +# ----------------------------------------------------------------------------- +# Query & Performance Limits +# ----------------------------------------------------------------------------- +# Resource limits to prevent expensive queries from affecting system performance + +# Trace query resource limits +trace: + # Maximum number of spans to return in a single query + # Prevents UI timeouts and excessive memory usage + # Users can adjust time ranges to stay within limits + #query_limit: 200_000 + + # Maximum memory usage per query (in bytes) + # Prevents OOM errors from complex queries + # Adjust based on available system memory + #max_memory_usage_bytes: 200_000_000 + +# ----------------------------------------------------------------------------- +# Feature Modules +# ----------------------------------------------------------------------------- +# Optional features that can be enabled/disabled for performance or security + +# Monitoring and alerting system +# Provides proactive monitoring with notifications +alerting: + # Uncomment to disable the entire alerting system + # This saves resources if you don't use monitoring alerts + #disabled: true -## -## Various options for Uptrace UI. -## -site: - # Overrides public URL for Vue-powered UI in case you put Uptrace behind a proxy. - #addr: 'https://uptrace.mydomain.com' +# Service dependency graph generation +# Automatically builds service topology from trace data +service_graph: + # Uncomment to disable service graph processing + # This saves CPU and memory if you don't use the service map + #disabled: true -## -## Spans processing options. -## -spans: - # The size of the Go chan used to buffer incoming spans. - # If the buffer is full, Uptrace starts to drop spans. - #buffer_size: 100000 +# JavaScript error sourcemap processing +# Provides better error stack traces for frontend applications +# Requires internet access to download source maps from URLs +sourcemaps: + # Uncomment to disable sourcemap processing + # Disable in air-gapped environments or if not using JS error tracking + #disabled: true - # The number of spans to insert in a single query. - #batch_size: 10000 +# ----------------------------------------------------------------------------- +# External Services +# ----------------------------------------------------------------------------- +# Integration with external services and self-monitoring -## -## Metrics processing options. -## -metrics: - # List of attributes to drop for being noisy. - drop_attrs: - - telemetry_sdk_language - - telemetry_sdk_name - - telemetry_sdk_version - - # The size of the Go chan used to buffer incoming measures. - # If the buffer is full, Uptrace starts to drop measures. - #buffer_size: 100000 - - # The number of measures to insert in a single query. - #batch_size: 10000 - -## -## uptrace-go client configuration. -## Uptrace sends internal telemetry here. Defaults to listen.grpc.addr. -## -uptrace_go: - # Enabled by default. +# Internal telemetry collection +# Uptrace monitors itself and sends telemetry to the configured DSN +self_monitoring: + # Uncomment to disable self-monitoring + # This prevents Uptrace from generating its own telemetry data #disabled: true - # Defaults to the first projects. - # dsn: http://project1_secret_token@localhost:14317/1 - - # tls: - # cert_file: config/tls/uptrace.crt - # key_file: config/tls/uptrace.key - # insecure_skip_verify: true - -## -## SMTP settings to send emails. -## https://uptrace.dev/get/alerting.html -## -smtp_mailer: - enabled: true - host: mailhog - port: 1025 - username: mailhog - password: mailhog - from: 'uptrace@localhost' - -## -## Logging configuration. -## + # DSN for internal telemetry + # Format: http://project_token@host?grpc=port + # This can point to a project in this Uptrace instance or to the Uptrace Cloud + dsn: http://project1_secret@localhost:14318?grpc=14317 + + #tls: + # insecure_skip_verify: true + +# Telegram bot for notifications +# Enables sending alert notifications to Telegram channels/users +# Setup guide: https://sendpulse.com/knowledge-base/chatbot/telegram/create-telegram-chatbot +telegram: + # Telegram bot token obtained from @BotFather + # Required for sending notifications to Telegram + bot_token: '' + +# ----------------------------------------------------------------------------- +# System Configuration +# ----------------------------------------------------------------------------- +# Global system settings and licensing + +# Application logging configuration +# Controls Uptrace's own log output (not application logs) logging: - # Zap minimal logging level. - # Valid values: DEBUG, INFO, WARN, ERROR, DPANIC, PANIC, FATAL. + # Log level affects verbosity and performance + # DEBUG: Very verbose, use only for troubleshooting + # INFO: Standard operational information + # WARN: Warning messages and errors + # ERROR: Only error messages level: INFO -# Secret key that is used to sign JWT tokens etc. -secret_key: 102c1a557c314fc28198acd017960843 - -# Enable to log HTTP requests and database queries. -debug: false +# Premium features license +# Enables advanced features like distributed tables, SSO, etc. +# Details: https://uptrace.dev/get/hosted#premium-edition +license: + # Premium license key from Uptrace + # Required for enterprise features + key: ''