OpenTelemetry Integration for Spryker

OPENTELEMETRY.md

OpenTelemetry Integration for Spryker

This document provides instructions for setting up and using the OpenTelemetry integration that has been added to the Spryker B2B Demo Shop.

Overview

OpenTelemetry has been integrated into this project to provide distributed tracing capabilities. The integration includes:

• Custom instrumentation for Spryker components
• Jaeger as the tracing backend
• Sampling configuration for both HTTP and CLI requests
• Support for the OpenTelemetry Protocol (OTLP) via gRPC

Changes Made

The following changes have been made to implement OpenTelemetry:

1. New Files:

   • _register.php: Registers OpenTelemetry instrumentation for various components
   • jeager.yml: Docker Compose configuration for the Jaeger service
   • otel_integration.sh: Script to automate the integration process
   • Custom implementation files in src/Pyz/Service/Opentelemetry/

2. Modified Files:

   • .env: Added OpenTelemetry environment variables
   • deploy.dev.yml: Updated to use a PHP image with OpenTelemetry support and include required extensions
   • src/Pyz/Zed/Console/ConsoleDependencyProvider.php: Added OpenTelemetry generator console command

Prerequisites

• Docker and Docker Compose
• PHP >8.0 with the following extensions:
  • opentelemetry
  • grpc
  • protobuf

Setup Instructions

1. Deploy yml

Spryker provides an image with opentelemetry extension already installed. To use it, you need to change your deploy.yml (and/or deploy.dev.yaml) file image section and enable the php extensions

image:
    tag: spryker/php:8.3-alpine3.20-otel
    php:
        ini:
            "opcache.revalidate_freq": 0
            "opcache.validate_timestamps": 0
        enabled-extensions:
            - opentelemetry
            - grpc
            - protobuf

If you want to use Jeager in your local environment for traces collector, you need to add the service in your deploy.dev.yml

docker:
    compose:
        yamls:
            - './jeager.yml'

and create a jeager.yml in your project root

version: '3.8'

services:
    jaeger:
        image: jaegertracing/jaeger:2.6.0
        container_name: jaeger
        networks:
            - private
        ports:
            - "16686:16686"
            - "4317:4317"
            - "4318:4318"
            - "5778:5778"
            - "9411:9411"
#        volumes:
#            - /path/to/local/config.yaml:/jaeger/config.yaml
#        command: ["--config", "/jaeger/config.yaml"]
        restart: "no"

2. Install required Spryker modules

composer require spryker/monitoring spryker/monitoring-extension spryker/opentelemetry:^1.0

3. Register the console command in the console dependency provider

protected function getConsoleCommands(Container $container): array
    {
        $commands = [
            new OpentelemetryGeneratorConsole(),

4. Register dependency in MonitoringDependencyProvider

namespace Pyz\Service\Monitoring;

use Spryker\Service\Monitoring\MonitoringDependencyProvider as SprykerMonitoringDependencyProvider;
use Spryker\Service\Opentelemetry\Plugin\OpentelemetryMonitoringExtensionPlugin;

class MonitoringDependencyProvider extends SprykerMonitoringDependencyProvider
{
    /**
     * @return array<\Spryker\Service\MonitoringExtension\Dependency\Plugin\MonitoringExtensionPluginInterface>
     */
    protected function getMonitoringExtensions(): array
    {
        return [
            new OpentelemetryMonitoringExtensionPlugin(),
        ];
    }
}

5. _register.php

Copy _register.php from the spryker-opentelemetry module to the project root. You will need to modify it if you want to override some of the Spryker default settings.

You need to register it in your composer.json in the files section of the autoload section:

{
  "autoload": {
    "files": [
      "./_register.php"
    ]
  }
}

6. Environment Configuration

Ensure the following environment variables are set in your .env file:

OTEL_EXPORTER_OTLP_ENDPOINT="http://jaeger:4317"
OTEL_SDK_DISABLED=false

Please note that when entering the CLI container env variables are not imported. This is the default Spryker behavior. This effectively means that telemetry is disabled in CLI and if you want to enable it, you will need to set environment variables manually when running the container.

4. Verify the Integration

After running the integration script, verify that:

1. The _register.php file is present at the project root
2. The Jaeger service is configured in jeager.yml
3. The custom OpenTelemetry classes are present in src/Pyz/Service/Opentelemetry/
4. The PHP image in your deployment configuration includes the required extensions

5. Start the Application with Jaeger

Start your application using the Docker SDK:

docker/sdk boot deploy.dev.yml
docker/sdk up

The Jaeger UI will be available at http://localhost:16686.

Generate hooks

To generate the hooks enter you cli container and run

console open-telemetry:generate

Custom Components

Sampling Configuration

The integration includes a custom sampling implementation in TraceSampleResult.php that allows you to control the sampling rate for both HTTP and CLI requests. The default configuration samples 100% of requests, but you can adjust this in OpentelemetryInstrumentationConfig.php:

public static function getTraceSamplerProbability(): float
{
    return 1.0; // 100% sampling, adjust as needed
}

public static function getTraceCLISamplerProbability(): float
{
    return 1.0; // 100% sampling, adjust as needed
}

What value to set depends on the expected traffic. Usually it is around 5% or 0.05.

Custom Instrumentation

The project includes a custom SprykerInstrumentationBootstrap class that extends the core Spryker implementation to add:

• Custom sampling logic
• Request filtering
• Proper shutdown handling

Troubleshooting

If you encounter issues with the OpenTelemetry integration:

1. Verify that the PHP extensions are properly installed:

   docker/sdk cli php -m | grep -E 'opentelemetry|grpc|protobuf'

2. Check that the Jaeger service is running:

   docker ps | grep jaeger

3. Ensure the environment variables are properly set:

   docker/sdk cli printenv | grep OTEL

4. Review the application logs for any OpenTelemetry-related errors.

Additional Resources

For more information about OpenTelemetry in Spryker, refer to the official documentation: https://docs.spryker.com/docs/ca/dev/monitoring/spryker-monitoring-integration/opentelemetry-instrumentation.html