The only tool you need to know what is happening and how to fix it.
Go alertingexception-trackerissue-trackinglogsmetricsmonitoringobservability-platformopen-telemetryotelsession-replaytelemetrytraces
Updated symfony docs
ddux5bdfd1cde41d
diff --git a/docs/pages/client/symfony/_meta.json b/docs/pages/client/symfony/_meta.jsonindex 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.mdxnew file mode 100644index 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.mdxindex 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 Tracewaydiff --git a/docs/pages/client/symfony/metrics.mdx b/docs/pages/client/symfony/metrics.mdxnew file mode 100644index 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.mdxnew file mode 100644index 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();+ }+ }+}+```