Gen Otlp Protobuf Laravel Package

Getting Started

Minimal Steps

1. Installation Add the package via Composer:

   composer require open-telemetry/gen-otlp-protobuf
   

   No additional configuration is required—this is a protobuf schema generator for OpenTelemetry Protocol (OTLP) in PHP.

2. First Use Case: Generating OTLP Protobuf Classes Use the gen-otlp-protobuf package to generate PHP classes from .proto files. This is typically done via a build script or CI pipeline:

   vendor/bin/protoc --php_out=. --plugin=protoc-gen-php=vendor/bin/protoc-gen-php \
     -I=vendor/open-telemetry/gen-otlp-protobuf/proto/otlp \
     vendor/open-telemetry/gen-otlp-protobuf/proto/otlp/*.proto
   

   This generates PHP classes (e.g., Span, Trace, Metric) in the current directory.

3. Where to Look First

   • Protobuf Definitions: Explore the protobuf schemas in the package’s proto/otlp directory.
   • Generated Classes: After running protoc, inspect the auto-generated classes (e.g., SpanProto, ResourceProto) in your project.
   • OpenTelemetry PHP SDK: Pair this with open-telemetry/sdk for actual instrumentation.

Implementation Patterns

Usage Patterns

1. Generating Protobuf Classes for OTLP Exports Integrate the protobuf generator into your build process (e.g., composer.json scripts):

   {
     "scripts": {
       "generate:protobuf": "vendor/bin/protoc --php_out=. --plugin=protoc-gen-php=vendor/bin/protoc-gen-php -I=vendor/open-telemetry/gen-otlp-protobuf/proto/otlp vendor/open-telemetry/gen-otlp-protobuf/proto/otlp/*.proto"
     }
   }
   

   Run with:

   composer generate:protobuf
   

2. Serializing Data for OTLP Collectors Use the generated classes to construct OTLP payloads (e.g., for exporting traces/metrics):

   use OpenTelemetry\Proto\Trace\V1\SpanProto;
   
   $span = new SpanProto();
   $span->setName("http.request");
   $span->setStartTimeUnixNano(1_000_000_000); // 1 second in nanoseconds
   $serialized = $span->serializeToString();
   

3. Integration with OpenTelemetry PHP SDK Combine with the OpenTelemetry PHP SDK to export data to OTLP endpoints:

   use OpenTelemetry\SDK\Trace\SpanProcessor\BatchSpanProcessor;
   use OpenTelemetry\SDK\Trace\SpanExporter\OtlpSpanExporter;
   
   $exporter = new OtlpSpanExporter(
       host: 'otel-collector:4317',
       insecure: true // For testing only!
   );
   $processor = new BatchSpanProcessor($exporter);
   $provider->addSpanProcessor($processor);
   

4. Custom Protobuf Extensions Extend the generated classes for domain-specific fields:

   // After generating protobuf classes, extend them:
   class CustomSpanProto extends SpanProto {
       public function setCustomAttribute(string $key, string $value) {
           $this->attributes[$key] = ['stringValue' => $value];
       }
   }
   

Workflows

• CI/CD Pipeline: Automate protobuf generation in CI (e.g., GitHub Actions) to ensure consistency.
• Local Development: Use a post-install script to regenerate protobuf classes when dependencies update.
• Testing: Mock OTLP payloads in unit tests by constructing protobuf objects manually.

Gotchas and Tips

Pitfalls

1. Protobuf Schema Changes

   • Issue: Updating the gen-otlp-protobuf package may break existing code if protobuf schemas change.
   • Fix: Version-lock the package and test thoroughly after updates. Use semantic versioning for protobuf-compatible changes.

2. Missing protoc Plugin

   • Issue: The protoc-gen-php plugin is required but not installed by default.
   • Fix: Install it via:

     composer require google/protobuf
     

3. Nanosecond Precision

   • Issue: OTLP expects timestamps in nanoseconds, but PHP’s microtime(true) returns seconds with microseconds.
   • Fix: Convert timestamps explicitly:

     $nanoseconds = (int) ($seconds * 1_000_000_000 + $microseconds * 1_000);
     

4. Circular Dependencies

   • Issue: Generated classes may have circular references (e.g., SpanProto ↔ ResourceProto).
   • Fix: Avoid deep nesting in custom extensions or use lazy-loading patterns.

Debugging

• Validate Protobuf Payloads: Use tools like buf or protoc --decode_raw to validate serialized data.
• Logging: Enable debug logging for the OpenTelemetry SDK to inspect exported payloads:

  \OpenTelemetry\SDK\Common\Instrumentation\Logger::setLogLevel(\Psr\Log\LogLevel::DEBUG);
  

Config Quirks

• OTLP Endpoint Configuration: Ensure the collector/server URL matches the protobuf schema version (e.g., v1 vs. v0.17.0).
• Compression: OTLP supports gRPC compression (e.g., gzip). Configure the exporter to handle it:

  $exporter = new OtlpSpanExporter(host: 'otel-collector:4317', compression: 'gzip');
  

Extension Points

1. Custom Protobuf Fields Define new .proto files in your project and generate additional classes alongside the OTLP schemas.

2. Protobuf Plugins Extend the protoc pipeline with custom plugins (e.g., for validation or transformation):

   vendor/bin/protoc --php_out=. --plugin=protoc-gen-custom=./custom-plugin ...
   

3. OpenTelemetry SDK Hooks Use the SDK’s SpanProcessor or MetricProcessor to intercept and modify protobuf payloads before export.