Opentelemetry Auto Class Symfony Laravel Package

Operational Impact

Maintenance

• Low Ongoing Effort:
  • No runtime configuration changes required after initial setup.
  • Updates may be needed for:
    • Symfony major versions (e.g., 6 → 7).
    • ext-opentelemetry or OpenTelemetry PHP SDK updates.
  • Monitor the monorepo for breaking changes.
• Dependency Management:
  • Pin eerzho/opentelemetry-auto-class-symfony and ext-opentelemetry versions in composer.json to avoid surprises.
  • Watch for deprecations in OpenTelemetry’s PHP API (e.g., span attribute limits).
• Attribute Maintenance:
  • Developers must manually add/remove #[Traceable] as business logic evolves.
  • Consider a naming convention (e.g., *Service classes) to avoid ad-hoc instrumentation.

Support

• Troubleshooting:
  • Common issues likely relate to:
    • Missing ext-opentelemetry or incorrect configuration.
    • Attribute syntax errors (e.g., typos in exclude).
    • OpenTelemetry exporter failures (e.g., network issues).
  • Debugging tools:
    • Symfony’s debug:container to verify instrumented services.
    • OpenTelemetry’s OTEL_PHP_DISABLED_INSTRUMENTATIONS=class to toggle tracing.
    • Jaeger/Datadog dashboards to validate spans.
• Community/Documentation:
  • Limited community support (0 stars, new package). Rely on:
    • Monorepo issues.
    • OpenTelemetry PHP documentation.
    • Symfony’s attribute/container docs.
  • Consider contributing to the project or forking if critical bugs arise.

Scaling

• Performance:
  • Container Compilation: Scanning for #[Traceable] attributes adds minimal overhead during cache:clear or cache:warmup. Test in staging with a large service count.
  • Runtime Overhead:
    • Span creation via ext-opentelemetry is optimized but may add ~1–5ms per traced method call.
    • Monitor CPU/memory in high-throughput services (e.g., API gateways).
  • Sampling: Use OpenTelemetry’s sampler (e.g., AlwaysOn, Probability) to reduce volume in high-cardinality systems.
• Distributed Tracing:
  • Scales well for microservices if:
    • All services are instrumented consistently.
    • Context propagation is enabled (e.g., HTTP headers, gRPC metadata).
  • Potential bottlenecks:
    • Excessive span attributes (e.g., large DTOs) may impact exporter throughput.
    • Cross-process tracing (e.g., message queues) requires additional setup (e.g., opentelemetry/php-instrumentation for AMQP).

Failure Modes

Ramp-Up

• Developer Onboarding:
  • Training: 30–60 minutes to:
    • Explain #[Traceable] usage and attribute options.
    • Demonstrate tracing in a sample service (e.g., OrderService).
    • Show how to exclude methods/arguments for sensitive data.
  • Documentation:
    • Add a Symfony-specific observability guide to the team wiki.
    • Include examples for:
      • Common use cases (e.g., API controllers, repositories).
      • Debugging missing spans (e.g., debug:container commands).
• CI/CD Integration:
  • Add a linting step to catch misconfigured #[Traceable] attributes (e.g., PHPStan rules).
  • Include tracing validation in end-to-end tests (e.g., verify spans for critical paths).
• Feedback Loop:
  • Gather input from developers on:
    • Attribute usability (e.g., default span names, attribute limits).
    • False positives/negatives in tracing.
  • Iterate based on pain points (e.g., add #[Traceable(ignore: true)] for opt-out).

Rollback Plan

1. Disable Instrumentation:
   • Set OTEL_PHP_DISABLED_INSTRUMENTATIONS=class in environment variables.
2. Revert Bundle:
   • Remove TraceableBundle from config/bundles.php.
   • Run composer remove eerzho/opentelemetry-auto-class-symfony.
3. Fallback to Manual Spans:
   • Revert to OpenTelemetry’s manual instrumentation (e.g., Tracer->spanBuilder()).
   • Example:

     use OpenTelemetry\API\Trace\TracerInterface;
     
     class OrderService {
         public function __construct(private TracerInterface $tracer) {}
     
         public function create(array $items): void {
             $span = $this->tracer->spanBuilder('OrderService::create')->startSpan();
             try {
                 // Business logic
             } finally {
                 $span->end();
             }
         }
     }
     

4. Monitor Impact:
   • Compare latency/throughput before/after rollback.
   • Verify no tracing data gaps in observability tools.