Browse documentation

#PHPUnit Telemetry Bridge

PHPUnit extension allowing to collect test suite telemetry and export it to any OTLP-compatible backend (OpenTelemetry Collector, Grafana Alloy, Honeycomb, Datadog, Jaeger, etc.).

#Installation

For detailed installation instructions, see the installation page.

#Configuration

Add the extension to your phpunit.xml.dist:

<extensions>
    <bootstrap class="Flow\Bridge\PHPUnit\Telemetry\TelemetryExtension">
        <parameter name="service_name" value="my-test-suite"/>
        <parameter name="endpoint" value="http://localhost:4318"/>
        <parameter name="emit_traces" value="true"/>
        <parameter name="emit_metrics" value="true"/>
        <parameter name="emit_test_spans" value="true"/>
        <parameter name="emit_test_case_spans" value="true"/>
    </bootstrap>
</extensions>

#Configuration Parameters

#Shared

#Curl transport (transport=curl)

Timeouts are in milliseconds (defaults assume a local collector on loopback / sidecar). timeout_ms is the per-request deadline; shutdown_timeout_ms (shared, see above) is a wall-clock budget enforced at shutdown only — it lets you keep timeout_ms tight for steady-state without freezing graceful exit.

#gRPC transport (transport=grpc)

Requires the grpc PHP extension and the google/protobuf package. Payload is always protobuf (per OTLP/gRPC spec). gRPC has no separate connect timeout — grpc_timeout_ms is the per-call deadline that bounds DNS, connect, send and receive together.

#Stream transport (transport=stream)

Writes JSONL telemetry to a file or php:// stream wrapper instead of an OTLP collector (OTLP File Exporter spec). The endpoint parameter holds the destination path. Useful for local debugging or pipelines that scrape JSONL from disk / stdout.

#Error Handlers

Telemetry-internal errors (exporter failures, transport timeouts) are routed to a configurable error handler instead of being thrown into the test runner. Pick one with the error_handler parameter; all options follow the same error_handler_* parameter family.

Mixing parameters across handler types throws InvalidArgumentException at boot.

#error_log (default)

#noop

No parameters. Use when you want telemetry-internal failures to stay silent (e.g. CI runs where the collector is intentionally absent).

#stream

Appends formatted Throwables (one per line) to a destination. The handle is opened lazily on first error and reused.

#syslog

#udp_syslog

Sends RFC 5424 syslog frames over UDP. Useful when test runs ship to a centralized log aggregator.

#Authentication

OTLP endpoints that require authentication (Grafana Alloy with Bearer auth, Honeycomb with x-honeycomb-team, vendor tenant headers, etc.) are configured through the headers parameter.

Headers use the OpenTelemetry spec format: comma-separated name=value pairs, with values URL-encoded (so commas, spaces and equal signs inside values don't collide with the delimiter):

<parameter name="endpoint" value="https://alloy.example.com:4318"/>
<parameter name="headers" value="Authorization=Bearer%20xxx,X-Scope-OrgID=tenant-1"/>

Invalid header format (missing =, empty name) will throw InvalidArgumentException when PHPUnit boots the extension.

#gRPC Transport

<extensions>
    <bootstrap class="Flow\Bridge\PHPUnit\Telemetry\TelemetryExtension">
        <parameter name="transport" value="grpc"/>
        <parameter name="endpoint" value="otel.example.com:4317"/>
        <parameter name="headers" value="api-key=xxx"/>
        <parameter name="grpc_insecure" value="false"/>
        <parameter name="grpc_timeout_ms" value="2000"/>
    </bootstrap>
</extensions>

#Stream Transport

<extensions>
    <bootstrap class="Flow\Bridge\PHPUnit\Telemetry\TelemetryExtension">
        <parameter name="transport" value="stream"/>
        <parameter name="endpoint" value="var/otel/test-suite.jsonl"/>
        <parameter name="error_handler" value="stream"/>
        <parameter name="error_handler_destination" value="var/otel/test-suite-errors.log"/>
    </bootstrap>
</extensions>

#Environment Variables

Every parameter has an env var counterpart (see the tables above).

Precedence: environment variable > <parameter> in phpunit.xml > default. Empty-string env vars are treated as unset.

Lookup order: $_ENV → $_SERVER → getenv(). Values loaded by Symfony DotEnv or vlucas/phpdotenv (which populate $_ENV / $_SERVER but don't always call putenv()) are picked up the same as shell env vars.

[!IMPORTANT] When setting boolean env vars through PHPUnit's <env> directive in phpunit.xml.dist, add verbatim="true" — otherwise PHPUnit casts the bare strings "true" / "false" to PHP booleans, which putenv() then stringifies to "1" / "", and the empty string is treated as unset by the resolver (falling back to the default).

<env name="FLOW_PHPUNIT_OTEL_EMIT_TEST_SPANS" value="false" verbatim="true"/>

This only applies to <env> in PHPUnit XML; real shell env vars and .env entries are already plain strings.

Typical usage — credentials stay out of version control:

export FLOW_PHPUNIT_OTEL_ENDPOINT="https://alloy.example.com:4318"
export FLOW_PHPUNIT_OTEL_HEADERS="Authorization=Bearer%20${ALLOY_TOKEN}"

./vendor/bin/phpunit

#Deprecation: otel_collector_url

The otel_collector_url parameter and its FLOW_PHPUNIT_OTEL_COLLECTOR_URL environment variable are deprecated and trigger E_USER_DEPRECATED. They remain functional as an alias for endpoint with transport=curl.

Mixing the deprecated parameter with any of the new-shape parameters throws InvalidArgumentException — migrate fully when you switch.

#Features

#Traces

When enabled, the extension creates spans for:

• Test suite runs (root span)
• Individual test suites
• Test case classes (optional)
• Individual tests (optional)

Each span includes attributes like:

• test.suite - Test suite name
• test.id - Test identifier
• test.name - Test name
• test.class - Test class name
• test.method - Test method name
• test.status - Test result status (passed, failed, errored, skipped, incomplete)

#Metrics

When enabled, the extension records:

• phpunit.suite.duration - Histogram of suite execution time
• phpunit.suite.test_count - Counter of tests per suite
• phpunit.test.duration - Histogram of individual test execution time
• phpunit.test.count - Counter of tests by status

#Running with Docker Compose

To visualize test telemetry, run an OTEL collector with a backend like Jaeger:

services:
  otel-collector:
    image: otel/opentelemetry-collector:latest
    ports:
      - "4317:4317"   # OTLP gRPC
      - "4318:4318"   # OTLP HTTP
    volumes:
      - ./otel-collector-config.yaml:/etc/otelcol/config.yaml

  jaeger:
    image: jaegertracing/all-in-one:latest
    ports:
      - "16686:16686" # UI

Then run your tests:

./vendor/bin/phpunit

View the traces in Jaeger at http://localhost:16686.

Found a typo or an outdated section? Edit this page on GitHub ↗