Add OpenTelemetry example with Uptrace backend (#2452)

* chore: add opentelemetry example

* chore: add opentelemetry API Jupyter notebook

* chore: use a shorter title

* chore: cleanup

Co-authored-by: dvora-h <[email protected]>

Author: vmihailenco

docs/conf.py

@@ -162,7 +162,7 @@
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ["_static"]
+html_static_path = ["_static", "images"]
 
 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
 # using the given strftime format.

docs/examples.rst

@@ -13,4 +13,5 @@ Examples
    examples/search_vector_similarity_examples
    examples/pipeline_examples
    examples/timeseries_examples
-   examples/redis-stream-example.ipynb
+   examples/redis-stream-example
+   examples/opentelemetry_api_examples

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.

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: "[email protected]"
+  smtp_require_tls: false
+
+receivers:
+  - name: "team-X"
+    email_configs:
+      - to: "[email protected]"
+        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"

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]

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"

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

docs/examples/opentelemetry/image/redis-py-trace.png

@@ -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()

docs/examples/opentelemetry/main.py

@@ -0,0 +1,3 @@
+redis==4.3.4
+uptrace==1.14.0
+opentelemetry-instrumentation-redis==0.35b0