Observability — OpenTelemetry

RoadRunner offers OTEL (OpenTelemetry) plugin, which provides a unified standard for tracing, logging, and metrics information. This plugin allows you to send tracing data from RoadRunner to tracing collectors like New Relic, Zipkin, Jaeger, Datadog, and more. Starting with v2023.3, the Jaeger exporter is deprecated. Please use OTLP instead: docs.

Note
Read more about OpenTelemetry on the official site.

The OpenTelemetry plugin is designed to integrate with various tracing collectors to provide end-to-end tracing of requests across multiple services. The plugin is built to support the OpenTelemetry standard, which provides a unified way of collecting telemetry data across various languages and frameworks.

The plugin supports tracing, logging, and metrics data, but currently only tracing information is stable and safe to use in production.

#Configuration

Here is an example configuration file:

version: "3"

otel:
  # https://github.com/open-telemetry/opentelemetry-specification/blob/v1.25.0/specification/resource/semantic_conventions/README.md
  resource:
    service_name: "rr_test"
    service_version: "1.0.0"
    service_namespace: "RR-Shop"
    service_instance_id: "UUID"
  insecure: true
  compress: false
  exporter: otlp
  endpoint: 127.0.0.1:4317

Once the plugin is activated, the grpc and jobs plugins will use the configuration to send tracing data to the collector. The http plugin requires the otel middleware to be added to the middleware list.

Here is an example:

http:
  address: 127.0.0.1:15389
  middleware: [ gzip, otel ]

...

The otel section of the configuration file contains the following options:

#Collector

The OpenTelemetry Collector offers a vendor-agnostic implementation of how to receive, process and export telemetry data. It removes the need to run, operate, and maintain multiple agents/collectors. This works with improved scalability and supports open-source observability data formats (e.g. Jaeger, Prometheus, Fluent Bit, etc.) sending to one or more open-source or commercial back-ends. The local Collector agent is the default location to which instrumentation libraries export their telemetry data.

To start the collector, you can use the official Docker container otel/opentelemetry-collector-contrib.

Here is an example docker-compose.yaml:

version: "3.6"

services:
  collector:
    image: otel/opentelemetry-collector-contrib
    command: [ "--config=/etc/otel-collector-config.yml" ]
    volumes:
      - ./otel-collector-config.yml:/etc/otel-collector-config.yml
    ports:
      - "4318:4318"
      - "4317:4317"

Note
Read more about the OpenTelemetry Collector on the official site.

#Collector Configuration

The collector is started with the otel-collector-config.yml configuration file, which specifies how the collector should receive, process, and export the tracing data.

Here is an example configuration file that sends data to Zipkin and Datadog:

receivers:
  otlp:
    protocols:
      grpc:
      http:

processors:
  batch:
    timeout: 1s

exporters:
  logging:
    loglevel: debug

  zipkin:
    endpoint: "http://zipkin:9411/api/v2/spans"

  datadog:
    api:
      site: datadoghq.eu
      key: ...

  otlp:
    endpoint: https://otlp.eu01.nr-data.net:443
    headers:
      api-key: ...

service:
  pipelines:
    traces:
      receivers: [ otlp ]
      processors: [ batch ]
      exporters: [ zipkin, datadog, otlp, logging ]

Note
Read more about the OpenTelemetry Collector configuration on the official site.

#PHP Client

The official PHP SDK for OpenTelemetry provides support for the OpenTelemetry standard on the PHP side.

To configure your PHP application to use the RoadRunner OpenTelemetry plugin, you need to use environment variables.

Here is an example of the required environment variables:

# OpenTelemetry
OTEL_SERVICE_NAME=php-blog
OTEL_TRACES_EXPORTER=otlp
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4318 # Collector address
OTEL_PHP_TRACES_PROCESSOR=simple

You can pass these environment variables to your PHP application from the RoadRunner configuration using the server.env option:

server:
  command: "php otel_worker.php"
  env:
    - OTEL_SERVICE_NAME: php
    - OTEL_TRACES_EXPORTER: otlp
    - OTEL_EXPORTER_OTLP_PROTOCOL: http/protobuf
    - OTEL_EXPORTER_OTLP_ENDPOINT: http://127.0.0.1:4318
    - OTEL_PHP_TRACES_PROCESSOR: simple
  relay: pipes

#Supported plugins:

Here is the list of currently supported plugin

Note
Thanks to Brett McBride, he created a rr-otel PHP demo.

#Original issue

• https://github.com/roadrunner-server/roadrunner/issues/1027