haoc/opentelemetry-laravel

Pacote de instrumentação OpenTelemetry para aplicações Laravel do HAOC.

Instalação

composer require haoc/opentelemetry-laravel

O package auto-discovery do Laravel registra o service provider automaticamente.

Desenvolvimento local: Se precisar testar alterações antes de publicar, use um repositório path no composer.json:

{
  "repositories": [{ "type": "path", "url": "../haoc-opentelemetry/packages/laravel" }],
  "require": { "haoc/opentelemetry-laravel": "*" }
}

Configuração

Publique o config (opcional):

php artisan vendor:publish --tag=haoc-otel-config

Variáveis de ambiente:

Middleware

Registre o middleware TraceRequest no Kernel ou nas rotas:

// bootstrap/app.php (Laravel 11+)
->withMiddleware(function (Middleware $middleware) {
    $middleware->append(\Haoc\OpenTelemetry\Middleware\TraceRequest::class);
})

// Ou no Kernel.php (Laravel 10)
protected $middleware = [
    \Haoc\OpenTelemetry\Middleware\TraceRequest::class,
];

O que o middleware captura

• http.method, http.route, http.url, http.status_code, http.duration_ms
• User Identity: haoc.user.id, haoc.user.email (do Auth)
• Infraestrutura: X-Forwarded-For, X-Real-IP, Via, network.hop_count
• Baggage do Frontend: atributos page.*, browser.*, device.*, app.*
• Query/Route/Body params (com redação de campos sensíveis)

Logging

Adicione o canal OTLP na config de logging:

// config/logging.php
'channels' => [
    'stack' => [
        'driver' => 'stack',
        'channels' => ['single', 'otlp'],
    ],
    'otlp' => [
        'driver' => 'custom',
        'via' => \Haoc\OpenTelemetry\Logging\OtelLogChannelFactory::class,
        'level' => env('LOG_LEVEL', 'debug'),
    ],
],

Docker

No docker-compose.yml, adicione a rede do SigNoz:

services:
  app:
    environment:
      - OTEL_SERVICE_NAME=meu-servico
      - OTEL_EXPORTER_OTLP_ENDPOINT=http://signoz-otel-collector:4318
      - OTEL_ENVIRONMENT=${APP_ENV-local}
    networks:
      - app
      - signoz

networks:
  signoz:
    name: signoz-shared
    external: true

Atributos Capturados (Spans)

Request (notação de ponto)

User Identity (do Auth Laravel)

Infraestrutura / Hops

Baggage do Frontend (W3C)

Dados Sensíveis (Redação Automática)

Campos automaticamente redatados como [REDACTED]:

password, senha, secret, token, access_token, refresh_token, authorization, db_password, network_password, tasy_password

Licença

MIT

Publicação (Packagist)

Este pacote é publicado no Packagist a partir de um subtree split do monorepo.

Passo a passo para publicar uma nova versão

# 1. No monorepo, commite suas alterações normalmente
cd /path/to/haoc-opentelemetry
git add -A && git commit -m "feat: descrição da alteração"
git push origin master

# 2. Atualize o subtree split para a branch dedicada
git subtree split --prefix=packages/laravel -b laravel-split

# 3. Push para o repositório dedicado do Packagist
git push laravel-origin laravel-split:master --force

# 4. Crie a tag de versão e envie
git tag vX.Y.Z laravel-split
git push laravel-origin vX.Y.Z

Configuração inicial (já feita)

O remote laravel-origin aponta para git@github.com:japostulo/opentelemetry-laravel.git.

Para verificar: git remote -v | grep laravel

Versionamento

Siga SemVer:

• patch (v1.0.1): correções de bugs
• minor (v1.1.0): novas funcionalidades retrocompatíveis
• major (v2.0.0): breaking changes

O Packagist lê as tags git automaticamente — o campo version no composer.json é ignorado quando há tags.

Atualizando nas aplicações consumidoras

composer update haoc/opentelemetry-laravel