Skip to content

The only tool you need to know what is happening and how to fix it.

Updated symfony docs

ddux5bdfd1cde41d
diff --git a/docs/pages/client/symfony/_meta.json b/docs/pages/client/symfony/_meta.json
index 8393d864..07583678 100644
--- a/docs/pages/client/symfony/_meta.json
+++ b/docs/pages/client/symfony/_meta.json
@@ -1,3 +1,6 @@
{
- "index": "Quick Start"
+ "index": "Quick Start",
+ "exceptions": "Exceptions",
+ "spans": "Spans",
+ "metrics": "Metrics"
}
diff --git a/docs/pages/client/symfony/exceptions.mdx b/docs/pages/client/symfony/exceptions.mdx
new file mode 100644
index 00000000..b4660031
--- /dev/null
+++ b/docs/pages/client/symfony/exceptions.mdx
@@ -0,0 +1,146 @@
+# Exceptions
+
+The OTel auto-instrumentation captures unhandled exceptions automatically. To report caught exceptions or add context to errors, use the OpenTelemetry PHP API directly.
+
+## Recording an Exception on the Current Span
+
+When you catch an error but want it reported to Traceway, record it as an event on the active span:
+
+```php
+use OpenTelemetry\API\Globals;
+use OpenTelemetry\API\Trace\StatusCode;
+
+try {
+ $this->paymentGateway->charge($order);
+} catch (\Throwable $e) {
+ $span = OpenTelemetry\API\Trace\Span::getCurrent();
+ $span->recordException($e);
+ $span->setStatus(StatusCode::STATUS_ERROR, $e->getMessage());
+
+ // Handle gracefully or re-throw
+ throw $e;
+}
+```
+
+`recordException` adds an `exception` event to the span with the type, message, and stack trace. Traceway extracts these events and creates Issues from them.
+
+## Adding Attributes to Exceptions
+
+Add context by setting span attributes before or after recording the exception:
+
+```php
+use OpenTelemetry\API\Trace\Span;
+use OpenTelemetry\API\Trace\StatusCode;
+
+$span = Span::getCurrent();
+
+$span->setAttribute('user.id', $userId);
+$span->setAttribute('order.id', $orderId);
+
+try {
+ $this->processOrder($orderId);
+} catch (\Throwable $e) {
+ $span->recordException($e, [
+ 'order.status' => 'failed',
+ 'retry.count' => $retryCount,
+ ]);
+ $span->setStatus(StatusCode::STATUS_ERROR, $e->getMessage());
+ throw $e;
+}
+```
+
+The additional attributes passed to `recordException` are attached to the exception event itself.
+
+## Capturing Exceptions in Services
+
+For exceptions in services outside of a controller, get the current span from context:
+
+```php
+namespace App\Service;
+
+use OpenTelemetry\API\Trace\Span;
+use OpenTelemetry\API\Trace\StatusCode;
+
+class PaymentService
+{
+ public function processPayment(string $customerId, float $amount): void
+ {
+ $span = Span::getCurrent();
+
+ try {
+ $this->gateway->charge($customerId, $amount);
+ } catch (\Throwable $e) {
+ $span->recordException($e, [
+ 'customer.id' => $customerId,
+ 'payment.amount' => $amount,
+ ]);
+ $span->setStatus(StatusCode::STATUS_ERROR, $e->getMessage());
+ throw $e;
+ }
+ }
+}
+```
+
+## Symfony Event Listener
+
+To capture all exceptions globally (including ones handled by Symfony's error system), register an event listener:
+
+```php
+// src/EventListener/ExceptionListener.php
+namespace App\EventListener;
+
+use OpenTelemetry\API\Trace\Span;
+use OpenTelemetry\API\Trace\StatusCode;
+use Symfony\Component\HttpKernel\Event\ExceptionEvent;
+
+class ExceptionListener
+{
+ public function onKernelException(ExceptionEvent $event): void
+ {
+ $span = Span::getCurrent();
+ $exception = $event->getThrowable();
+
+ $span->recordException($exception);
+ $span->setStatus(StatusCode::STATUS_ERROR, $exception->getMessage());
+ }
+}
+```
+
+Register it in `config/services.yaml`:
+
+```yaml
+services:
+ App\EventListener\ExceptionListener:
+ tags:
+ - { name: kernel.event_listener, event: kernel.exception }
+```
+
+## Custom Error Types
+
+Custom exception classes work the same way. The exception type name appears in the Traceway dashboard:
+
+```php
+class InsufficientFundsException extends \RuntimeException
+{
+ public function __construct(
+ public readonly string $accountId,
+ public readonly float $requested,
+ public readonly float $available,
+ ) {
+ parent::__construct("Insufficient funds: requested {$requested}, available {$available}");
+ }
+}
+
+// When caught and recorded, Traceway shows "InsufficientFundsException" as the type
+try {
+ $this->withdraw($accountId, $amount);
+} catch (InsufficientFundsException $e) {
+ $span = Span::getCurrent();
+ $span->recordException($e, [
+ 'account.id' => $e->accountId,
+ 'amount.requested' => $e->requested,
+ 'amount.available' => $e->available,
+ ]);
+ $span->setStatus(StatusCode::STATUS_ERROR, $e->getMessage());
+}
+```
diff --git a/docs/pages/client/symfony/index.mdx b/docs/pages/client/symfony/index.mdx
index 87ec69da..d0275e56 100644
--- a/docs/pages/client/symfony/index.mdx
+++ b/docs/pages/client/symfony/index.mdx
@@ -156,5 +156,7 @@ Visit `/testing` in your browser, then check the Traceway dashboard — the exce
## Next Steps
-- [OpenTelemetry docs](/client/otel) — learn more about how OTel traces and metrics map to Traceway
-- [Connection page](/client/otel#connection-page) — grab your project-specific config from the dashboard
+- [Exceptions](/client/symfony/exceptions) — manually capture caught exceptions with context
+- [Spans](/client/symfony/spans) — create custom spans to measure sub-operations
+- [Metrics](/client/symfony/metrics) — track custom counters, histograms, and gauges
+- [OpenTelemetry docs](/client/otel) — how OTel traces and metrics map to Traceway
diff --git a/docs/pages/client/symfony/metrics.mdx b/docs/pages/client/symfony/metrics.mdx
new file mode 100644
index 00000000..af1c2274
--- /dev/null
+++ b/docs/pages/client/symfony/metrics.mdx
@@ -0,0 +1,187 @@
+# Metrics
+
+The OTel auto-instrumentation captures basic request metrics automatically. To track custom application-specific metrics, use the OpenTelemetry PHP API to create counters, gauges, and histograms.
+
+## Creating a Meter
+
+Get a meter instance from the global meter provider:
+
+```php
+use OpenTelemetry\API\Globals;
+
+$meter = Globals::meterProvider()->getMeter('app');
+```
+
+## Counter
+
+Counters track cumulative values that only go up (e.g., total orders, requests processed):
+
+```php
+$meter = Globals::meterProvider()->getMeter('app');
+$orderCounter = $meter->createCounter('orders.created', 'orders', 'Total orders created');
+
+// Increment by 1
+$orderCounter->add(1);
+
+// Increment with attributes
+$orderCounter->add(1, ['plan' => 'pro', 'region' => 'eu']);
+```
+
+## Histogram
+
+Histograms track distributions of values (e.g., response times, payload sizes):
+
+```php
+$meter = Globals::meterProvider()->getMeter('app');
+$durationHistogram = $meter->createHistogram('order.processing_ms', 'ms', 'Order processing time');
+
+$start = hrtime(true);
+$this->processOrder($order);
+$durationMs = (hrtime(true) - $start) / 1e6;
+
+$durationHistogram->record($durationMs);
+```
+
+Traceway converts histograms into average and count metrics (see [OTel metrics](/client/otel/metrics#histogram-handling)).
+
+## Gauge
+
+Gauges track point-in-time values that can go up or down (e.g., queue depth, active connections):
+
+```php
+$meter = Globals::meterProvider()->getMeter('app');
+
+// Observable gauge — value is read by a callback at export time
+$meter->createObservableGauge('queue.size', 'items', 'Current queue depth')
+ ->observe(function ($observer) {
+ $observer->observe($this->queue->count());
+ });
+```
+
+## Use Cases
+
+### Business Metrics
+
+```php
+$meter = Globals::meterProvider()->getMeter('app');
+$revenueCounter = $meter->createCounter('payments.revenue', 'usd', 'Total revenue');
+$signupCounter = $meter->createCounter('users.signups', 'users', 'Total signups');
+
+// In your payment service
+public function processPayment(Order $order): void
+{
+ $this->gateway->charge($order->total);
+ $revenueCounter->add($order->total, ['plan' => $order->plan]);
+}
+
+// In your registration controller
+public function register(Request $request): Response
+{
+ $user = $this->userService->create($request);
+ $signupCounter->add(1);
+ return new JsonResponse($user, 201);
+}
+```
+
+### Performance Metrics
+
+```php
+$meter = Globals::meterProvider()->getMeter('app');
+$apiLatency = $meter->createHistogram('external_api.latency_ms', 'ms', 'External API call duration');
+
+public function fetchExternalData(string $endpoint): array
+{
+ $start = hrtime(true);
+ try {
+ return $this->client->request('GET', $endpoint)->toArray();
+ } finally {
+ $durationMs = (hrtime(true) - $start) / 1e6;
+ $apiLatency->record($durationMs, ['endpoint' => $endpoint]);
+ }
+}
+```
+
+### Resource Metrics
+
+```php
+$meter = Globals::meterProvider()->getMeter('app');
+
+$meter->createObservableGauge('cache.entries', 'items', 'Cache entry count')
+ ->observe(function ($observer) {
+ $observer->observe($this->cache->getStats()['entries']);
+ });
+
+$meter->createObservableGauge('cache.memory_mb', 'MB', 'Cache memory usage')
+ ->observe(function ($observer) {
+ $observer->observe($this->cache->getStats()['memory'] / 1024 / 1024);
+ });
+```
+
+## Metric Naming Conventions
+
+Use dot-separated names for organization:
+
+```php
+// Good naming
+$meter->createCounter('orders.created');
+$meter->createHistogram('db.query_ms');
+$meter->createCounter('cache.hits');
+
+// Bad naming
+$meter->createCounter('created'); // Too vague
+$meter->createCounter('orderCount'); // Inconsistent style
+```
+
+## Registering Metrics as a Service
+
+Define your meters in a Symfony service for dependency injection:
+
+```php
+// src/Telemetry/AppMetrics.php
+namespace App\Telemetry;
+
+use OpenTelemetry\API\Globals;
+use OpenTelemetry\API\Metrics\CounterInterface;
+use OpenTelemetry\API\Metrics\HistogramInterface;
+
+class AppMetrics
+{
+ public readonly CounterInterface $ordersCreated;
+ public readonly HistogramInterface $orderProcessingMs;
+ public readonly CounterInterface $paymentSuccess;
+ public readonly CounterInterface $paymentFailed;
+
+ public function __construct()
+ {
+ $meter = Globals::meterProvider()->getMeter('app');
+
+ $this->ordersCreated = $meter->createCounter('orders.created', 'orders');
+ $this->orderProcessingMs = $meter->createHistogram('orders.processing_ms', 'ms');
+ $this->paymentSuccess = $meter->createCounter('payments.success', 'payments');
+ $this->paymentFailed = $meter->createCounter('payments.failed', 'payments');
+ }
+}
+```
+
+Then inject it where needed:
+
+```php
+class OrderService
+{
+ public function __construct(
+ private readonly AppMetrics $metrics,
+ ) {}
+
+ public function createOrder(array $items): Order
+ {
+ $start = hrtime(true);
+ try {
+ $order = $this->doCreateOrder($items);
+ $this->metrics->ordersCreated->add(1);
+ return $order;
+ } finally {
+ $this->metrics->orderProcessingMs->record((hrtime(true) - $start) / 1e6);
+ }
+ }
+}
+```
diff --git a/docs/pages/client/symfony/spans.mdx b/docs/pages/client/symfony/spans.mdx
new file mode 100644
index 00000000..9d6f9460
--- /dev/null
+++ b/docs/pages/client/symfony/spans.mdx
@@ -0,0 +1,190 @@
+# Spans
+
+The OTel auto-instrumentation creates spans for HTTP requests automatically. To measure sub-operations like database queries, API calls, or business logic, create spans manually using the OpenTelemetry PHP API.
+
+## Creating a Span
+
+Use the tracer to start and end spans:
+
+```php
+use OpenTelemetry\API\Globals;
+
+$tracer = Globals::tracerProvider()->getTracer('app');
+
+$span = $tracer->spanBuilder('process-order')->startSpan();
+try {
+ $this->processOrder($orderId);
+} finally {
+ $span->end();
+}
+```
+
+Always end spans in a `finally` block to ensure they are closed even if an exception is thrown.
+
+## Activating a Span
+
+To make a span the current active span (so child spans and exceptions are linked to it), activate it with a scope:
+
+```php
+use OpenTelemetry\API\Globals;
+
+$tracer = Globals::tracerProvider()->getTracer('app');
+
+$span = $tracer->spanBuilder('checkout')->startSpan();
+$scope = $span->activate();
+try {
+ // Any spans created here become children of "checkout"
+ $this->validateCart($cart);
+ $this->processPayment($payment);
+ $this->sendConfirmation($order);
+} finally {
+ $scope->detach();
+ $span->end();
+}
+```
+
+## Nested Spans
+
+Create child spans to break down an operation into sub-steps:
+
+```php
+use OpenTelemetry\API\Globals;
+
+$tracer = Globals::tracerProvider()->getTracer('app');
+
+$parentSpan = $tracer->spanBuilder('create-order')->startSpan();
+$parentScope = $parentSpan->activate();
+try {
+ // Child span: validate
+ $validateSpan = $tracer->spanBuilder('validate-items')->startSpan();
+ $this->validateItems($items);
+ $validateSpan->end();
+
+ // Child span: inventory check
+ $inventorySpan = $tracer->spanBuilder('check-inventory')->startSpan();
+ $this->checkInventory($items);
+ $inventorySpan->end();
+
+ // Child span: payment
+ $paymentSpan = $tracer->spanBuilder('process-payment')->startSpan();
+ $this->processPayment($paymentInfo);
+ $paymentSpan->end();
+} finally {
+ $parentScope->detach();
+ $parentSpan->end();
+}
+```
+
+Child spans are automatically linked to the active parent span.
+
+## Adding Attributes
+
+Attach metadata to spans for filtering and debugging:
+
+```php
+$span = $tracer->spanBuilder('db-query')->startSpan();
+$span->setAttribute('db.system', 'mysql');
+$span->setAttribute('db.statement', 'SELECT * FROM users WHERE id = ?');
+$span->setAttribute('db.row_count', $rowCount);
+$span->end();
+```
+
+## Recording Errors on Spans
+
+When a span's operation fails, record the exception and set the status:
+
+```php
+use OpenTelemetry\API\Trace\StatusCode;
+
+$span = $tracer->spanBuilder('external-api-call')->startSpan();
+try {
+ $response = $this->httpClient->request('GET', 'https://api.example.com/data');
+} catch (\Throwable $e) {
+ $span->recordException($e);
+ $span->setStatus(StatusCode::STATUS_ERROR, $e->getMessage());
+ throw $e;
+} finally {
+ $span->end();
+}
+```
+
+## Span Naming Conventions
+
+Use descriptive names that indicate the operation type:
+
+| Good | Bad |
+|------|-----|
+| `db.users.find` | `query` |
+| `cache.sessions.get` | `cache` |
+| `stripe.charge` | `api` |
+| `s3.upload-image` | `upload` |
+| `email.send-welcome` | `send` |
+
+## Database Wrapper Example
+
+```php
+use OpenTelemetry\API\Globals;
+
+class TracedRepository
+{
+ private $tracer;
+
+ public function __construct(
+ private readonly Connection $connection,
+ ) {
+ $this->tracer = Globals::tracerProvider()->getTracer('app');
+ }
+
+ public function query(string $sql, array $params = []): array
+ {
+ $span = $this->tracer->spanBuilder('db.query')->startSpan();
+ $span->setAttribute('db.statement', $sql);
+ try {
+ $result = $this->connection->fetchAllAssociative($sql, $params);
+ $span->setAttribute('db.row_count', count($result));
+ return $result;
+ } catch (\Throwable $e) {
+ $span->recordException($e);
+ $span->setStatus(\OpenTelemetry\API\Trace\StatusCode::STATUS_ERROR, $e->getMessage());
+ throw $e;
+ } finally {
+ $span->end();
+ }
+ }
+}
+```
+
+## HTTP Client Wrapper Example
+
+```php
+use OpenTelemetry\API\Globals;
+
+class TracedHttpClient
+{
+ private $tracer;
+
+ public function __construct(
+ private readonly HttpClientInterface $client,
+ ) {
+ $this->tracer = Globals::tracerProvider()->getTracer('app');
+ }
+
+ public function request(string $method, string $url, array $options = []): ResponseInterface
+ {
+ $span = $this->tracer->spanBuilder("http.{$method}")->startSpan();
+ $span->setAttribute('http.method', $method);
+ $span->setAttribute('http.url', $url);
+ try {
+ $response = $this->client->request($method, $url, $options);
+ $span->setAttribute('http.status_code', $response->getStatusCode());
+ return $response;
+ } catch (\Throwable $e) {
+ $span->recordException($e);
+ $span->setStatus(\OpenTelemetry\API\Trace\StatusCode::STATUS_ERROR, $e->getMessage());
+ throw $e;
+ } finally {
+ $span->end();
+ }
+ }
+}
+```