README

Flow OpenTelemetry

OpenTelemetry integration for Neos Flow with tracing, logging and metrics

📦 Packagist • Quick Start • Functionality

Quick Start

Important

This package integrates OpenTelemetry into Neos Flow by providing a pre-configured tracer, logger, meter, and automatic tracing aspects.

Just add these environment variables and you are good to go:

• OTEL_EXPORTER_OTLP_ENDPOINT: The URL to your OTLP-compatible endpoint (e.g., Grafana Tempo, Jaeger)
• OTEL_SERVICE_NAME: The name of your service
• OTEL_SERVICE_VERSION: The version of your service

SigNoz

A fast way to get anything out of this package is to use SigNoz. For bigger setups Grafana with its extensions is still a better choice but for smaller setups and playing around SigNoz is sufficient.

Official Guide to Install SigNoz using docker compose

OpenTelemetry Collector

For production environments, it is recommended to use the OpenTelemetry Collector (otelcol) as a central telemetry processing layer for each project.

Each log, trace/span and metric is sent and may take some time. Sending all of that synchronously over the network can impact performance. The OpenTelemetry Collector is installed ideally locally next to the project or with a low-latency high-speed connection in-between. It acts as a buffer that sends every received data via the specified exporter.

Configure the Collector (otelcol-config.yaml):

receivers:
  otlp:
    protocols:
      http:
        endpoint: 0.0.0.0:4318

processors:
  batch:

exporters:
  otlp_http/signoz:
    endpoint: http://signoz:4318
    tls:
      insecure: true

service:
  telemetry:
    metrics:
      level: basic
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlp_http/signoz]

    metrics:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlp_http/signoz]

    logs:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlp_http/signoz]

For more configuration examples, see the OpenTelemetry Collector documentation.

Functionality

Logging Backend

A logging backend that sends logs to OpenTelemetry.

Class: SJS\Flow\OpenTelemetry\Log\Backend\OpenTelemetryBackend

Options

Example

Configuration/Settings.Neos.Flow.log.yaml

Neos:
  Flow:
    log:
      psr3:
        'Neos\Flow\Log\PsrLoggerFactory':
          systemLogger:
            default:
              class: SJS\Flow\OpenTelemetry\Log\Backend\OpenTelemetryBackend
              options:
                severityThreshold: "%LOG_NOTICE%"
                attributes:
                  logger: "systemLogger"
          securityLogger:
            default:
              class: SJS\Flow\OpenTelemetry\Log\Backend\OpenTelemetryBackend
              options:
                severityThreshold: "%LOG_NOTICE%"
                attributes:
                  logger: "securityLogger"

Tracing Aspects

Built-in AOP aspects that automatically create spans for common Flow operations.

Class: SJS\Flow\OpenTelemetry\Aspects\SpanAspect

Available Aspects

Example

Configuration/Settings.yaml

SJS:
  Flow:
    OpenTelemetry:
      builtInAspect:
        enableAdvice:
          commandController: true
          actionController: true
          viewInterfaceRender: true
          repository: true
          fusionCacheEvents: true
      setup:
        default:
          class: SJS\Flow\OpenTelemetry\Setup\OpenTelemetrySetup
          uri: "%env:OTEL_EXPORTER_OTLP_ENDPOINT%"
          service:
            name: "%env:OTEL_SERVICE_NAME%"
            version: "%env:OTEL_SERVICE_VERSION%"

HTTP Response Middleware

Middleware that records HTTP response status as a metric.

Class: SJS\Flow\OpenTelemetry\Middleware\HttpResponseStatusMiddleware

Example

Configuration/Settings.Neos.Flow.yaml

Neos:
  Flow:
    http:
      middlewares:
        'httpResponseStatus':
          position: 'end 50'
          middleware: 'SJS\Flow\OpenTelemetry\Middleware\HttpResponseStatusMiddleware'

Configuration Reference

Configuration/Settings.yaml