Getting Started

Install the package via Composer:

composer require open-telemetry/sem-conv

This package provides only constants—no runtime logic—so its value is in standardizing attribute and metric names used elsewhere in your telemetry stack (e.g., with open-telemetry/sdk). Start by importing the relevant classes:

use OpenTelemetry\SemConv\Attributes\SpanAttributes;
use OpenTelemetry\SemConv\Metrics\SystemMetrics;

First use case: When instrumenting HTTP requests in Laravel middleware or HTTP clients, replace raw strings with constants:

$span->setAttribute(SpanAttributes::HTTP_METHOD, $request->getMethod());
$span->setAttribute(SpanAttributes::HTTP_STATUS_CODE, $response->getStatusCode());
$span->setAttribute(SpanAttributes::HTTP_TARGET, $request->path());

💡 Tip: Use IDE autocomplete (e.g., SpanAttributes:: + tab) to explore and safely use conventions.

Implementation Patterns

1. Span & Log Attribute Consistency

Always prefer SpanAttributes, ExceptionAttributes, DbAttributes, and NetAttributes over string literals. This ensures your traces align with backend expectations (e.g., Datadog’s span tags, Prometheus metric labels).

2. Metrics with Semantic Names

Use Metrics\* classes to define standardized metrics:

$meter = $meterProvider->getMeter('app');
$meter->createHistogram(SystemMetrics::SYSTEM_MEMORY_USAGE)
    ->record(memory_get_usage(), ['state' => 'used']);

This guarantees compatibility with OTel-promoted dashboards and alerts.

3. Incubating Features (Use Sparingly)

For new features like deployment attributes (DeploymentAttributes) or TLS trace attributes (TlsAttributes), use the Incubating namespace only when necessary:

use OpenTelemetry\SemConv\Incubating\Attributes\DeploymentAttributes;

$span->setAttribute(DeploymentAttributes::DEPLOYMENT_ENVIRONMENT, config('app.env'));

Always check the changelog for stability notes—experimental attributes may change/remove.

4. Automated Attribute Injection

In Laravel, create reusable helpers to attach common conventions:

function otel_span_attributes(\Illuminate\Http\Request $request): array
{
    return [
        SpanAttributes::HTTP_METHOD => $request->getMethod(),
        SpanAttributes::HTTP_URL => $request->url(),
        SpanAttributes::HTTP_USER_AGENT => $request->userAgent(),
        SpanAttributes::CLIENT_IP => $request->ip(),
    ];
}

Then apply in middleware or service calls.

Gotchas and Tips

⚠️ Breaking Changes in SemConv Versions

Deprecations are removed without warning—e.g., HTTP_FLAVOR became HTTP_SERVER_REQUEST_PROTOCOL in newer versions. Always check the changelog for your sem-conv version.
Attributes may be renamed or restructured internally (e.g., 1.36.0 refactor).

🔍 Debugging & Verification

Use php artisan tinker to inspect available constants:
```
>>> get_class_constants(SpanAttributes::class);
```
Run grep -r "http.method" app/ to find hardcoded strings and refactor them.

⚙️ Version Pinning

Lock sem-conv to patch versions (e.g., "open-telemetry/sem-conv": "^1.38.0") to avoid accidental breaking changes from new semconv releases. Align with your OpenTelemetry SDK version (e.g., open-telemetry/sdk ^1.0 supports sem-conv ^1.38).

🛠️ When Not to Use Incubating

Avoid incubating attributes in libraries or public APIs—stick to Stable conventions (OpenTelemetry\SemConv\Attributes\*) unless:

You control both producer and consumer (e.g., internal metrics),
You’re okay with migrating conventions on upgrades.

📦 Laravel-Specific Integration

Add to service providers to automatically enrich spans with request data:

// App\Providers\TracingServiceProvider
$span->setAttributes(otel_span_attributes(app('request')));

Use in HTTP client instrumentation:

$client->request('GET', 'https://api.example.com', [
    'open_telemetry_attributes' => [
        SpanAttributes::PEER_SERVICE => 'api.example.com',
        SpanAttributes::HTTP_METHOD => 'GET',
    ],
]);

Sem Conv Laravel Package