Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/tracewayapp/opentelemetry-symfony-bundle/llms.txt

Use this file to discover all available pages before exploring further.

bin/console traceway:doctor runs a suite of diagnostic checks across runtime extensions, SDK environment variables, bundle wiring, and OTLP endpoint reachability. Run it after installation, after changing environment variables, or in CI to catch misconfigurations before they reach production. The command is also discoverable in the debug: namespace as debug:traceway.

​
Terminal output

Below is an example of what the command prints when everything is healthy: 
$ bin/console traceway:doctor
Traceway Doctor
═══════════════

Runtime
  ○ protocol is http/json; ext-protobuf not required
  ✓ ext-opentelemetry not loaded (no conflict risk)

SDK configuration
  ✓ OTEL_SERVICE_NAME = "my-symfony-app"
  ✓ OTEL_TRACES_EXPORTER = otlp
  ✓ OTEL_EXPORTER_OTLP_ENDPOINT = http://localhost/api/otel
  ✓ OTEL_EXPORTER_OTLP_PROTOCOL = http/json
  ✓ OTEL_TRACES_SAMPLER unset (defaults to parentbased_always_on)
  ✓ TracerProvider is TracerProvider

Bundle configuration
  ○ propagator=w3c, id_generator=default; X-Ray not configured
  ✓ Messenger tracing enabled and symfony/messenger is installed
  ○ logs.export.enabled is false

Connectivity
  ✓ OTLP endpoint reachable (HTTP 404, 7ms)

Results: 9 ok, 0 warning, 0 error, 3 skipped, 0 info

​
Flags

Each flag adjusts what the command checks and how it exits.
FlagDefaultPurpose
--format=text|jsontextjson emits a stable versioned envelope for CI consumption
--skip-networkoffSkip reachability checks — useful in CI without a live backend
--only=name1,name2allRestrict the run to a comma-separated list of check names
--fail-on=info|warning|errorerrorSeverity threshold that triggers exit code 1
--timeout=N1.0Network probe timeout in seconds

​
Checks performed

The command runs checks across four groups, each corresponding to a section in the output.

Runtime

Extension conflicts and protocol prerequisites:
  • ext-opentelemetry — flags conflict risk if the experimental C extension is loaded alongside the PHP SDK
  • ext-protobuf — required only when OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
  • gRPC transport — required only when OTEL_EXPORTER_OTLP_PROTOCOL=grpc

SDK Configuration

Environment variable validation:
  • OTEL_SERVICE_NAME — warns when unset
  • OTEL_TRACES_EXPORTER and OTEL_EXPORTER_OTLP_ENDPOINT
  • OTEL_EXPORTER_OTLP_PROTOCOL and OTEL_TRACES_SAMPLER
  • Active TracerProvider class

Bundle Configuration

Symfony wiring checks:
  • Messenger middleware registration in the bus chain
  • OtelLogHandler registration when log export is enabled
  • AWS X-Ray dependency presence when X-Ray propagator or ID generator is configured

Connectivity

Network reachability:
  • OTLP endpoint probe — fires an HTTP request to OTEL_EXPORTER_OTLP_ENDPOINT and reports status code and latency
  • Skipped entirely when --skip-network is passed or when the check implements NetworkCheckInterface

​
CI usage

The JSON output is stable and safe to parse in scripts. The envelope always contains version, summary, and checks. 
bin/console traceway:doctor --format=json --skip-network | jq '.summary.exit_code'

bin/console traceway:doctor --format=json --skip-network
Exits with code 1 only when at least one check reaches the error severity. Safe for most pipelines — skips noise from informational and warning-level results.
The JSON envelope shape ({version, summary, checks}) is considered stable API and will not change without a major version bump. It is safe to script against in CI pipelines.

​
Custom checks

Doctor is extensible through the traceway.doctor.check service tag. Implement CheckInterface and Symfony’s autoconfigure wiring handles the rest.

​
CheckInterface

interface CheckInterface
{
    /** @return non-empty-string */
    public function name(): string;

    /** @return non-empty-string */
    public function label(): string;

    public function group(): CheckGroup;

    public function run(CheckContext $context): CheckResult;
}

​
CheckResult factory methods

CheckResult::ok(string $name, string $message, array $details = []): CheckResult
CheckResult::warning(string $name, string $message, ?string $remediation = null, array $details = []): CheckResult
CheckResult::error(string $name, string $message, ?string $remediation = null, array $details = []): CheckResult
CheckResult::info(string $name, string $message, array $details = []): CheckResult
CheckResult::skipped(string $name, string $reason): CheckResult

​
Full example

namespace App\Doctor;

use Traceway\OpenTelemetryBundle\Command\Doctor\Check\CheckInterface;
use Traceway\OpenTelemetryBundle\Command\Doctor\Check\CheckGroup;
use Traceway\OpenTelemetryBundle\Command\Doctor\Check\CheckResult;
use Traceway\OpenTelemetryBundle\Command\Doctor\Support\CheckContext;

final class MyCheck implements CheckInterface
{
    public function name(): string { return 'my_check'; }
    public function label(): string { return 'My custom check'; }
    public function group(): CheckGroup { return CheckGroup::Bundle; }

    public function run(CheckContext $context): CheckResult
    {
        return CheckResult::ok($this->name(), 'all good');
    }
}
If your check performs network I/O (for example, probing a secondary endpoint), implement NetworkCheckInterface instead of CheckInterface. The command will skip it automatically when --skip-network is passed, keeping your CI pipelines fast when no backend is available.

​
Available check groups

enum CheckGroup: string
{
    case Runtime      = 'runtime';
    case Sdk          = 'sdk';
    case Bundle       = 'bundle';
    case Connectivity = 'connectivity';
}
Assign your custom check to CheckGroup::Bundle for app-specific wiring checks, or CheckGroup::Connectivity combined with NetworkCheckInterface for endpoint probes.

Build docs developers (and LLMs) love

Get started for freeTalk to us