Browse documentation

#PHPUnit Telemetry Bridge

A PHPUnit extension that collects test suite telemetry. It exports the telemetry to each OTLP-compatible backend, for example OpenTelemetry Collector, Grafana Alloy, Honeycomb, Datadog or Jaeger.

#Installation

For the installation instructions, read 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="resource_attributes" value="service.version=1.0.0,deployment.environment.name=ci"/>
        <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"/>
        <parameter name="memory_real_usage" value="false"/>
    </bootstrap>
</extensions>

#Configuration Parameters

#Shared

#Curl transport (transport=curl)

Timeouts are in milliseconds. The defaults expect a local collector on loopback / sidecar. timeout_ms is the deadline of each request. shutdown_timeout_ms (shared, read above) is a wall-clock budget, enforced only at shutdown. You can therefore keep timeout_ms tight for steady-state, and the graceful exit does not freeze.

#gRPC transport (transport=grpc)

Needs the grpc PHP extension and the google/protobuf package. The payload is always protobuf, as the OTLP/gRPC specification says. gRPC has no separate connect timeout. grpc_timeout_ms is the deadline of each call, for DNS, connect, send and receive together.

#Stream transport (transport=stream)

Writes JSONL telemetry to a file or a php:// stream wrapper, not to an OTLP collector. The format follows the OTLP File Exporter spec here. The endpoint parameter holds the destination path. Use it for local debugging, or for pipelines that read JSONL from disk / stdout.

#Error Handlers

Internal telemetry errors (exporter failures, transport timeouts) go to a configurable error handler. They are not thrown into the test runner. Pick a handler with the error_handler parameter. All options use the same error_handler_* parameter family.

Parameters of different handler types together throw InvalidArgumentException at boot.

#error_log (default)

#noop

No parameters. Use it to keep internal telemetry failures silent, for example in CI runs without a collector.

#stream

Appends formatted Throwables (one per line) to a destination. The handle opens lazily at the first error and is used again after that.

#syslog

#udp_syslog

Sends RFC 5424 syslog frames over UDP. Use it to send test run errors to a central log aggregator.

#Authentication

Configure OTLP endpoints that need authentication through the headers parameter. Examples are Grafana Alloy with Bearer auth, Honeycomb with x-honeycomb-team, and vendor tenant headers.

Headers use the OpenTelemetry specification format: comma-separated name=value pairs, with URL-encoded values. Commas, spaces and equal signs inside values therefore do not 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"/>

An invalid header format (missing =, empty name) throws InvalidArgumentException at the boot of 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

Each parameter has an environment variable counterpart (read the tables above).

Precedence: environment variable > <parameter> in phpunit.xml > default. An environment variable with an empty string counts as unset.

Lookup order: $_ENV → $_SERVER → getenv(). Symfony DotEnv and vlucas/phpdotenv fill $_ENV / $_SERVER, but they do not always call putenv(). Values that they load still work in the same way as shell environment variables.

[!IMPORTANT] To set boolean environment variables through the <env> directive of PHPUnit in phpunit.xml.dist, add verbatim="true". Without it, PHPUnit casts the bare strings "true" / "false" to PHP booleans. putenv() then turns them into the strings "1" / "". The resolver treats the empty string as unset and uses the default.

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

This applies only to <env> in PHPUnit XML. Real shell environment variables and .env entries are already plain strings.

Typical usage, with the credentials outside 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 they trigger E_USER_DEPRECATED. They still work as an alias for endpoint with transport=curl.

The deprecated parameter together with one of the new-shape parameters throws InvalidArgumentException. When you switch, migrate fully.

#Features

#Traces

When traces are enabled, the extension creates spans for:

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

Each span has attributes such as:

• test.suite.name: test suite name
• test.suite.run.status: suite outcome (success, failure, skipped)
• test.case.name: test name
• test.case.result.status: test result status (passed, failed, errored, skipped, incomplete)
• flow.phpunit.test.id: test identifier
• flow.phpunit.test.class: test class name
• flow.phpunit.test.method: test method name
• flow.phpunit.test.memory.peak / flow.phpunit.test.memory.delta: memory usage in bytes

#Metrics

When metrics are enabled, the extension records:

• flow.phpunit.suite.duration: histogram of suite execution time (seconds)
• flow.phpunit.suite.test_count: counter of tests per suite ({test})
• flow.phpunit.test.duration: histogram of individual test execution time (seconds)
• flow.phpunit.test.count: counter of tests by status ({test})
• flow.phpunit.test.memory.peak / flow.phpunit.test.memory.delta: memory histograms (By)

#Running with Docker Compose

To see the test telemetry, run an OTEL collector with a backend such as 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 ↗