Skip to main content

Telemetry

This tutorial enables logs and metrics on a single Kafka Gateway instance. It does not need Kafka at all: an echo binding stands in for a backend, so you can see how telemetry is configured and collected before wiring it up to a real Kafka topic.

Prerequisites

Enable logs and metrics

Create zilla.yaml:

zilla.yaml
name: Metrics-example
telemetry:

  # Desired metrics to track
  metrics:
    - http.request.size
    - http.response.size
    - stream.opens.sent
    - stream.closes.sent

  exporters:
    # Enable Standard Out logs
    stdout_logs_exporter:
      type: stdout
    # Prometheus endpoint definition
    prometheus_metric_exporter:
      type: prometheus
      options:
        endpoints:
          - scheme: http
            path: /metrics
            port: 7190

# Sample HTTP Echo service
bindings:
  north_tcp_server:
    type: tcp
    kind: server
    options:
      host: 0.0.0.0
      port: 7114
    telemetry:
      metrics:
        - stream.*
    exit: north_http_server
  north_http_server:
    type: http
    kind: server
    routes:
      - when:
          - headers:
              :scheme: http
              :authority: localhost:7114
        exit: north_echo_server
    telemetry:
      metrics:
        - http.*
  north_echo_server:
    type: echo
    kind: server

The telemetry.metrics list opts into four metrics: http.request.size, http.response.size, stream.opens.sent, and stream.closes.sent. Each binding then selects which of those metrics it reports with its own telemetry.metrics entry. The highlighted stdout_logs_exporter writes access logs to standard out, and prometheus_metric_exporter exposes the collected metrics on a /metrics HTTP endpoint on port 7190.

Run Zilla with telemetry

docker run -d -v ./zilla.yaml:/etc/zilla/zilla.yaml \
--name zilla-sample -p 7114:7114 -p 7190:7190 \
ghcr.io/aklivity/zilla:latest \
start

Send an HTTP POST

curl -d "Hello, world" -H "Content-Type: text/plain" -X "POST" http://localhost:7114/
Hello, world

The echo binding returns the request body unchanged, so a successful response confirms the stack is up.

View the standard out logs

docker logs zilla-sample
started
Metrics-example.north_http_server [08/May/2024:18:46:13 +0000] REQUEST_ACCEPTED - http POST localhost:7114 /
Metrics-example.north_http_server [08/May/2024:18:46:14 +0000] REQUEST_ACCEPTED - http POST localhost:7114 /

View the Prometheus metrics

Go to http://localhost:7190/metrics or run:

curl http://localhost:7190/metrics
# TYPE stream_opens_sent_total counter
stream_opens_sent_total{namespace="Metrics-example",binding="tcp_server"} 2

# HELP stream_closes_sent_total Number of closed sent streams
stream_closes_sent_total{namespace="Metrics-example",binding="tcp_server"} 2

# HELP http_request_size_bytes HTTP request content length
...
http_request_size_bytes_sum{namespace="Metrics-example",binding="http_server"} 30

# HELP http_response_size_bytes HTTP response content length
...
http_response_size_bytes_sum{namespace="Metrics-example",binding="http_server"} 30

Clean up

docker rm -f zilla-sample

Next Steps