diff options
Diffstat (limited to 'docs/examples/opentelemetry')
-rw-r--r-- | docs/examples/opentelemetry/README.md | 47 | ||||
-rw-r--r-- | docs/examples/opentelemetry/config/alertmanager.yml | 53 | ||||
-rw-r--r-- | docs/examples/opentelemetry/config/otel-collector.yaml | 68 | ||||
-rw-r--r-- | docs/examples/opentelemetry/config/vector.toml | 39 | ||||
-rw-r--r-- | docs/examples/opentelemetry/docker-compose.yml | 81 | ||||
-rw-r--r-- | docs/examples/opentelemetry/image/redis-py-trace.png | bin | 0 -> 18252 bytes | |||
-rwxr-xr-x | docs/examples/opentelemetry/main.py | 56 | ||||
-rw-r--r-- | docs/examples/opentelemetry/requirements.txt | 3 | ||||
-rw-r--r-- | docs/examples/opentelemetry/uptrace.yml | 297 |
9 files changed, 644 insertions, 0 deletions
diff --git a/docs/examples/opentelemetry/README.md b/docs/examples/opentelemetry/README.md new file mode 100644 index 0000000..a1d1c04 --- /dev/null +++ b/docs/examples/opentelemetry/README.md @@ -0,0 +1,47 @@ +# Example for redis-py OpenTelemetry instrumentation + +This example demonstrates how to monitor Redis using [OpenTelemetry](https://opentelemetry.io/) and +[Uptrace](https://github.com/uptrace/uptrace). It requires Docker to start Redis Server and Uptrace. + +See +[Monitoring redis-py performance with OpenTelemetry](https://redis-py.readthedocs.io/en/latest/opentelemetry.html) +for details. + +**Step 1**. Download the example using Git: + +```shell +git clone https://github.com/redis/redis-py.git +cd example/opentelemetry +``` + +**Step 2**. Optionally, create a virtualenv: + +```shell +python3 -m venv .venv +source .venv/bin/active +``` + +**Step 3**. Install dependencies: + +```shell +pip install -r requirements.txt +``` + +**Step 4**. Start the services using Docker and make sure Uptrace is running: + +```shell +docker-compose up -d +docker-compose logs uptrace +``` + +**Step 5**. Run the Redis client example and follow the link from the CLI to view the trace: + +```shell +python3 main.py +trace: http://localhost:14318/traces/ee029d8782242c8ed38b16d961093b35 +``` + +![Redis trace](./image/redis-py-trace.png) + +You can also open Uptrace UI at [http://localhost:14318](http://localhost:14318) to view available +spans, logs, and metrics. diff --git a/docs/examples/opentelemetry/config/alertmanager.yml b/docs/examples/opentelemetry/config/alertmanager.yml new file mode 100644 index 0000000..ac3e340 --- /dev/null +++ b/docs/examples/opentelemetry/config/alertmanager.yml @@ -0,0 +1,53 @@ +# See https://prometheus.io/docs/alerting/latest/configuration/ for details. + +global: + # The smarthost and SMTP sender used for mail notifications. + smtp_smarthost: "mailhog:1025" + smtp_from: "alertmanager@example.com" + smtp_require_tls: false + +receivers: + - name: "team-X" + email_configs: + - to: "some-receiver@example.com" + send_resolved: true + +# The root route on which each incoming alert enters. +route: + # The labels by which incoming alerts are grouped together. For example, + # multiple alerts coming in for cluster=A and alertname=LatencyHigh would + # be batched into a single group. + group_by: ["alertname", "cluster", "service"] + + # When a new group of alerts is created by an incoming alert, wait at + # least 'group_wait' to send the initial notification. + # This way ensures that you get multiple alerts for the same group that start + # firing shortly after another are batched together on the first + # notification. + group_wait: 30s + + # When the first notification was sent, wait 'group_interval' to send a batch + # of new alerts that started firing for that group. + group_interval: 5m + + # If an alert has successfully been sent, wait 'repeat_interval' to + # resend them. + repeat_interval: 3h + + # A default receiver + receiver: team-X + + # All the above attributes are inherited by all child routes and can + # overwritten on each. + + # The child route trees. + routes: + # This route matches error alerts created from spans or logs. + - matchers: + - alert_kind="error" + group_interval: 24h + receiver: team-X + +# The directory from which notification templates are read. +templates: + - "/etc/alertmanager/template/*.tmpl" diff --git a/docs/examples/opentelemetry/config/otel-collector.yaml b/docs/examples/opentelemetry/config/otel-collector.yaml new file mode 100644 index 0000000..b44dd1f --- /dev/null +++ b/docs/examples/opentelemetry/config/otel-collector.yaml @@ -0,0 +1,68 @@ +extensions: + health_check: + pprof: + endpoint: 0.0.0.0:1777 + zpages: + endpoint: 0.0.0.0:55679 + +receivers: + otlp: + protocols: + grpc: + http: + hostmetrics: + collection_interval: 10s + scrapers: + cpu: + disk: + load: + filesystem: + memory: + network: + paging: + redis: + endpoint: "redis-server:6379" + collection_interval: 10s + jaeger: + protocols: + grpc: + +processors: + resourcedetection: + detectors: ["system"] + batch: + send_batch_size: 10000 + timeout: 10s + +exporters: + logging: + logLevel: debug + otlp: + endpoint: uptrace:14317 + tls: + insecure: true + headers: { "uptrace-dsn": "http://project2_secret_token@localhost:14317/2" } + +service: + # telemetry: + # logs: + # level: DEBUG + pipelines: + traces: + receivers: [otlp, jaeger] + processors: [batch] + exporters: [otlp, logging] + metrics: + receivers: [otlp] + processors: [batch] + exporters: [otlp] + metrics/hostmetrics: + receivers: [hostmetrics, redis] + processors: [batch, resourcedetection] + exporters: [otlp] + logs: + receivers: [otlp] + processors: [batch] + exporters: [otlp] + + extensions: [health_check, pprof, zpages] diff --git a/docs/examples/opentelemetry/config/vector.toml b/docs/examples/opentelemetry/config/vector.toml new file mode 100644 index 0000000..10db91d --- /dev/null +++ b/docs/examples/opentelemetry/config/vector.toml @@ -0,0 +1,39 @@ +[sources.syslog_logs] +type = "demo_logs" +format = "syslog" +interval = 0.1 + +[sources.apache_common_logs] +type = "demo_logs" +format = "apache_common" +interval = 0.1 + +[sources.apache_error_logs] +type = "demo_logs" +format = "apache_error" +interval = 0.1 + +[sources.json_logs] +type = "demo_logs" +format = "json" +interval = 0.1 + +# Parse Syslog logs +# See the Vector Remap Language reference for more info: https://vrl.dev +[transforms.parse_logs] +type = "remap" +inputs = ["syslog_logs"] +source = ''' +. = parse_syslog!(string!(.message)) +''' + +# Export data to Uptrace. +[sinks.uptrace] +type = "http" +inputs = ["parse_logs", "apache_common_logs", "apache_error_logs", "json_logs"] +encoding.codec = "json" +framing.method = "newline_delimited" +compression = "gzip" +uri = "http://uptrace:14318/api/v1/vector/logs" +#uri = "https://api.uptrace.dev/api/v1/vector/logs" +headers.uptrace-dsn = "http://project2_secret_token@localhost:14317/2" diff --git a/docs/examples/opentelemetry/docker-compose.yml b/docs/examples/opentelemetry/docker-compose.yml new file mode 100644 index 0000000..ea1d6dc --- /dev/null +++ b/docs/examples/opentelemetry/docker-compose.yml @@ -0,0 +1,81 @@ +version: "3" + +services: + clickhouse: + image: clickhouse/clickhouse-server:22.7 + restart: on-failure + environment: + CLICKHOUSE_DB: uptrace + healthcheck: + test: ["CMD", "wget", "--spider", "-q", "localhost:8123/ping"] + interval: 1s + timeout: 1s + retries: 30 + volumes: + - ch_data:/var/lib/clickhouse + ports: + - "8123:8123" + - "9000:9000" + + uptrace: + image: "uptrace/uptrace:1.2.0" + #image: 'uptrace/uptrace-dev:latest' + restart: on-failure + volumes: + - uptrace_data:/var/lib/uptrace + - ./uptrace.yml:/etc/uptrace/uptrace.yml + #environment: + # - DEBUG=2 + ports: + - "14317:14317" + - "14318:14318" + depends_on: + clickhouse: + condition: service_healthy + + otel-collector: + image: otel/opentelemetry-collector-contrib:0.58.0 + restart: on-failure + volumes: + - ./config/otel-collector.yaml:/etc/otelcol-contrib/config.yaml + ports: + - "4317:4317" + - "4318:4318" + + vector: + image: timberio/vector:0.24.X-alpine + volumes: + - ./config/vector.toml:/etc/vector/vector.toml:ro + + alertmanager: + image: prom/alertmanager:v0.24.0 + restart: on-failure + volumes: + - ./config/alertmanager.yml:/etc/alertmanager/config.yml + - alertmanager_data:/alertmanager + ports: + - 9093:9093 + command: + - "--config.file=/etc/alertmanager/config.yml" + - "--storage.path=/alertmanager" + + mailhog: + image: mailhog/mailhog:v1.0.1 + restart: on-failure + ports: + - "8025:8025" + + redis-server: + image: redis + ports: + - "6379:6379" + redis-cli: + image: redis + +volumes: + uptrace_data: + driver: local + ch_data: + driver: local + alertmanager_data: + driver: local diff --git a/docs/examples/opentelemetry/image/redis-py-trace.png b/docs/examples/opentelemetry/image/redis-py-trace.png Binary files differnew file mode 100644 index 0000000..e443238 --- /dev/null +++ b/docs/examples/opentelemetry/image/redis-py-trace.png diff --git a/docs/examples/opentelemetry/main.py b/docs/examples/opentelemetry/main.py new file mode 100755 index 0000000..b140dd0 --- /dev/null +++ b/docs/examples/opentelemetry/main.py @@ -0,0 +1,56 @@ +#!/usr/bin/env python3 + +import time + +import uptrace +from opentelemetry import trace +from opentelemetry.instrumentation.redis import RedisInstrumentor + +import redis + +tracer = trace.get_tracer("app_or_package_name", "1.0.0") + + +def main(): + uptrace.configure_opentelemetry( + dsn="http://project2_secret_token@localhost:14317/2", + service_name="myservice", + service_version="1.0.0", + ) + RedisInstrumentor().instrument() + + client = redis.StrictRedis(host="localhost", port=6379) + + span = handle_request(client) + print("trace:", uptrace.trace_url(span)) + + for i in range(10000): + handle_request(client) + time.sleep(1) + + +def handle_request(client): + with tracer.start_as_current_span( + "handle-request", kind=trace.SpanKind.CLIENT + ) as span: + client.get("my-key") + client.set("hello", "world") + client.mset( + { + "employee_name": "Adam Adams", + "employee_age": 30, + "position": "Software Engineer", + } + ) + + pipe = client.pipeline() + pipe.set("foo", 5) + pipe.set("bar", 18.5) + pipe.set("blee", "hello world!") + pipe.execute() + + return span + + +if __name__ == "__main__": + main() diff --git a/docs/examples/opentelemetry/requirements.txt b/docs/examples/opentelemetry/requirements.txt new file mode 100644 index 0000000..2132801 --- /dev/null +++ b/docs/examples/opentelemetry/requirements.txt @@ -0,0 +1,3 @@ +redis==4.3.4 +uptrace==1.14.0 +opentelemetry-instrumentation-redis==0.35b0 diff --git a/docs/examples/opentelemetry/uptrace.yml b/docs/examples/opentelemetry/uptrace.yml new file mode 100644 index 0000000..4cb39f8 --- /dev/null +++ b/docs/examples/opentelemetry/uptrace.yml @@ -0,0 +1,297 @@ +## +## 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: + # Connection string for ClickHouse database. For example: + # clickhouse://<user>:<password>@<host>:<port>/<database>?sslmode=disable + # + # See https://clickhouse.uptrace.dev/guide/golang-clickhouse.html#options + dsn: "clickhouse://default:@clickhouse:9000/uptrace?sslmode=disable" + +## +## 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 + + # 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 spans by deployment.environment attribute. + group_by_env: false + # Group funcs spans by service.name attribute. + group_funcs_by_service: false + +## +## Create metrics from spans and events. +## +metrics_from_spans: + - name: uptrace.tracing.spans_duration + description: Spans duration (excluding events) + instrument: histogram + unit: microseconds + value: span.duration / 1000 + attrs: + - span.system as system + - service.name as service + - host.name as host + - span.status_code as status + where: not span.is_event + + - name: uptrace.tracing.spans + description: Spans count (excluding events) + instrument: counter + unit: 1 + value: span.count + attrs: + - span.system as system + - service.name as service + - host.name as host + - span.status_code as status + where: not span.is_event + + - name: uptrace.tracing.events + description: Events count (excluding spans) + instrument: counter + unit: 1 + value: span.count + attrs: + - span.system as system + - service.name as service + - host.name as host + where: span.is_event + +## +## To require authentication, uncomment the following section. +## +auth: + # users: + # - username: uptrace + # password: uptrace + # - username: admin + # password: admin + + # # Cloudflare user provider: uses 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://<uptrace-host>/api/v1/sso/<oidc-id>/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 + # # The OIDC UserInfo claim to use as the user's username. + # # Defaults to 'preferred_username'. + # claim: preferred_username + +## +## Alerting rules for monitoring metrics. +## +## See https://uptrace.dev/get/alerting.html for details. +## +alerting: + rules: + - name: Network errors + metrics: + - system.network.errors as $net_errors + query: + - $net_errors > 0 group by host.name + # for the last 5 minutes + for: 5m + annotations: + summary: "{{ $labels.host_name }} has high number of net errors: {{ $values.net_errors }}" + + - name: Filesystem usage >= 90% + metrics: + - system.filesystem.usage as $fs_usage + query: + - group by host.name + - group by device + - where device !~ "loop" + - $fs_usage{state="used"} / $fs_usage >= 0.9 + for: 5m + annotations: + summary: "{{ $labels.host_name }} has high FS usage: {{ $values.fs_usage }}" + + - name: Uptrace is dropping spans + metrics: + - uptrace.projects.spans as $spans + query: + - $spans{type=dropped} > 0 + for: 1m + annotations: + summary: "Uptrace has dropped {{ $values.spans }} spans" + + - name: Always firing (for fun and testing) + metrics: + - process.runtime.go.goroutines as $goroutines + query: + - $goroutines >= 0 group by host.name + for: 1m + annotations: + summary: "{{ $labels.host_name }} has high number of goroutines: {{ $values.goroutines }}" + + # Create alerts from error logs and span events. + create_alerts_from_spans: + enabled: true + labels: + alert_kind: error + +## +## AlertManager client configuration. +## See https://uptrace.dev/get/alerting.html for details. +## +## Note that this is NOT an AlertManager config and you need to configure AlertManager separately. +## See https://prometheus.io/docs/alerting/latest/configuration/ for details. +## +alertmanager_client: + # AlertManager API endpoints that Uptrace uses to manage alerts. + urls: + - "http://alertmanager:9093/api/v2/alerts" + +## +## 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) + + # Whether to use ReplicatedMergeTree instead of MergeTree. + replicated: false + + # Cluster name for Distributed tables and ON CLUSTER clause. + #cluster: uptrace1 + + spans: + storage_policy: "default" + # Delete spans data after 30 days. + ttl_delete: 30 DAY + + metrics: + storage_policy: "default" + # Delete metrics data after 90 days. + ttl_delete: 90 DAY + +## +## Addresses on which Uptrace receives gRPC and HTTP requests. +## +listen: + # OTLP/gRPC API. + grpc: + addr: ":14317" + # tls: + # cert_file: config/tls/uptrace.crt + # key_file: config/tls/uptrace.key + + # OTLP/HTTP API and Uptrace API with UI. + http: + addr: ":14318" + # tls: + # cert_file: config/tls/uptrace.crt + # key_file: config/tls/uptrace.key + +## +## 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' + +## +## 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 + + # The number of spans to insert in a single query. + #batch_size: 10000 + +## +## 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 + +## +## SQLite/PostgreSQL db that is used to store metadata such us metric names, dashboards, alerts, +## and so on. +## +db: + # Either sqlite or postgres. + driver: sqlite + # Database connection string. + # + # Uptrace automatically creates SQLite database file in the current working directory. + # Make sure the directory is writable by Uptrace process. + dsn: "file:uptrace.sqlite3?_pragma=foreign_keys(1)&_pragma=busy_timeout(1000)" + +# Secret key that is used to sign JWT tokens etc. +secret_key: 102c1a557c314fc28198acd017960843 + +# Enable to log HTTP requests and database queries. +debug: false |