feat: exporters (OTLP, Datadog, Sentry, PostHog) and diagnostics

.github/workflows/ci.yml

@@ -106,6 +106,8 @@ jobs:
   mutation:
     name: Mutation testing
     runs-on: ubuntu-latest
+    # The full run takes about 8 minutes; a hanging mutant holds a thread for the 120 s Infection timeout.
+    timeout-minutes: 45
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:

infection.json5

@@ -6,6 +6,9 @@
     "logs": {
         "text": ".cache/infection.log"
     },
+    // Seconds per mutant. A mutant whose covering tests take longer is skipped, not run: the transport
+    // helpers are covered by the whole delivery suite, which takes longer than the default 10 s.
+    "timeout": 120,
     "minMsi": 90,
     "minCoveredMsi": 95,
     "mutators": {

src/AgentCat.php

@@ -83,8 +83,9 @@ public static function publishCustomEvent(object|string $serverOrSessionId, ?str
      *
      * @param float|null $timeoutSeconds The longest wait in seconds; null waits until nothing is left to send.
      *
-     * @return bool True when nothing is left to send (every event delivered, or given up after its retries); false
-     *              when the timeout ended first.
+     * @return bool True when nothing is left to send (every event delivered, or given up after its retries, and no
+     *              exporter request left); false when the timeout ended first. AgentCat's own diagnostics are neither
+     *              counted nor waited for: they go out on their own, between requests and when the process ends.
      */
     public static function flush(?float $timeoutSeconds = null): bool
     {

src/Client.php

@@ -7,6 +7,7 @@
 use AgentCat\Internal\ClientSeams;
 use AgentCat\Internal\Constants;
 use AgentCat\Internal\Delivery\EventQueue;
+use AgentCat\Internal\Diagnostics\Diagnostics;
 use AgentCat\Internal\Engine\CallInterceptor;
 use AgentCat\Internal\Engine\Publisher;
 use AgentCat\Internal\Engine\TrackedServer;
@@ -18,6 +19,7 @@
 use AgentCat\Internal\Support\TestMode;
 use AgentCat\Internal\Support\Values;
 use AgentCat\Internal\Tags\TagValidator;
+use AgentCat\Internal\Telemetry\TelemetryManager;
 use AgentCat\McpSdk\McpSdkAdapter;
 use Psr\Log\LoggerInterface;
 
@@ -39,6 +41,8 @@
     /** @var \Closure(): bool */
     private \Closure $enabled;
 
+    private bool $telemetry;
+
     /**
      * Creates a client that sends through the process-wide event queue. Call it without arguments. A
      * dependency-injection container that autowires it gets the same client.
@@ -50,6 +54,7 @@
         $this->publisher = new Publisher($seams->queue ?? EventQueue::global());
         $this->interceptor = new CallInterceptor($this->publisher);
         $this->enabled = $seams->enabled ?? TestMode::sdkEnabled(...);
+        $this->telemetry = $seams->telemetry ?? true;
     }
 
     /**
@@ -82,6 +87,13 @@
             }
             $options ??= new Options();
             $projectId ??= Env::get('AGENTCAT_PROJECT_ID') ?? ''; // D36: '' means telemetry only
+            if ($this->telemetry) {
+                // TS: the first statement of track(), before the server is checked; the first call in the process decides.
+                Diagnostics::init($projectId, $options->disableDiagnostics, $this->publisher->queue());
+            }
+            if ($options->disableSignalHandlers && !$this->publisher->queue()->disableSignalHandlers() && $this->publisher->queue()->claimSignalHandlersWarning()) {
+                Log::write('WARN: AgentCat signal handlers are already installed; disableSignalHandlers is ignored');
+            }
             if (!McpSdkAdapter::supports($server)) {
                 $signals = McpSdkAdapter::fingerprint($server);
                 Log::warning(sprintf('AgentCat SDK Compatibility: unrecognized server shape | signals %s. %s', $signals === '' ? '(none)' : $signals, McpSdkAdapter::SUPPORT_MATRIX));
@@ -106,20 +118,24 @@
 
                 return $server;
             }
-            if ($projectId === '') {
+            if ($this->telemetry) {
+                TelemetryManager::install($this->publisher->queue(), $options->exporters); // first wins (TypeScript)
+            }
+            if ($projectId === '' && $options->exporters === null) {
                 Log::write('Warning: No projectId provided and no exporters configured. Events will not be sent anywhere.');
-            } elseif (preg_match(self::PROJECT_ID_PATTERN, $projectId) !== 1) {
+            } elseif ($projectId !== '' && preg_match(self::PROJECT_ID_PATTERN, $projectId) !== 1) {
                 Log::write(sprintf('WARN: Project ID "%s" does not match proj_ followed by 27 letters or digits; the AgentCat API drops its events', $projectId));
             }
             $state = new TrackedServer($projectId, $options, McpSdkAdapter::serverInfo($server), $this->publisher);
             McpSdkAdapter::install($server, $state, $this->publisher, $this->interceptor);
             TrackedServers::add($server, $state);
             Log::write(sprintf(
-                'AgentCat setup complete | project %s | tracing=%s context=%s reportMissing=%s exporters=0',
+                'AgentCat setup complete | project %s | tracing=%s context=%s reportMissing=%s exporters=%d',
                 $project,
                 $options->enableTracing ? 'true' : 'false',
                 $options->enableToolCallContext ? 'true' : 'false',
                 $options->enableReportMissing ? 'true' : 'false',
+                count($options->exporters ?? []),
             ));
 
             return $server;
@@ -228,8 +244,9 @@
      *
      * @param float|null $timeoutSeconds The longest wait in seconds; null waits until nothing is left to send.
      *
-     * @return bool True when nothing is left to send (every event delivered, or given up after its retries); false
-     *              when the timeout ended first.
+     * @return bool True when nothing is left to send (every event delivered, or given up after its retries, and no
+     *              exporter request left); false when the timeout ended first. AgentCat's own diagnostics are neither
+     *              counted nor waited for: they go out on their own, between requests and when the process ends.
      */
     public function flush(?float $timeoutSeconds = null): bool
     {

src/Exporters/DatadogExporter.php

@@ -0,0 +1,25 @@
+<?php
+
+declare(strict_types=1);
+
+namespace AgentCat\Exporters;
+
+/**
+ * Sends each event to Datadog's log and metric intake (not APM traces). Use it in
+ * `Options(exporters: ['datadog' => new DatadogExporter(apiKey: '…', site: 'datadoghq.com', service: 'my-mcp')])`.
+ */
+final readonly class DatadogExporter
+{
+    /**
+     * @param string      $apiKey  Your Datadog API key.
+     * @param string      $site    Your Datadog site, for example `datadoghq.com` or `datadoghq.eu`.
+     * @param string      $service The service name of the logs and metrics.
+     * @param string|null $env     Adds an `env:` tag to the logs and metrics. Default: null (no tag).
+     */
+    public function __construct(
+        public string $apiKey,
+        public string $site,
+        public string $service,
+        public ?string $env = null,
+    ) {}
+}

src/Exporters/OtlpExporter.php

@@ -0,0 +1,21 @@
+<?php
+
+declare(strict_types=1);
+
+namespace AgentCat\Exporters;
+
+/**
+ * Sends each event as one span to an OTLP/HTTP JSON collector. Use it in
+ * `Options(exporters: ['otlp' => new OtlpExporter(endpoint: 'http://localhost:4318')])`.
+ */
+final readonly class OtlpExporter
+{
+    /**
+     * @param string                $endpoint The collector base URL. `/v1/traces` is added unless it is there already.
+     * @param array<string, string> $headers  Extra request headers, for example an API key. A `Content-Type` here replaces `application/json`. Default: none.
+     */
+    public function __construct(
+        public string $endpoint,
+        public array $headers = [],
+    ) {}
+}

src/Exporters/PostHogExporter.php

@@ -0,0 +1,23 @@
+<?php
+
+declare(strict_types=1);
+
+namespace AgentCat\Exporters;
+
+/**
+ * Sends each event to PostHog's batch API as a capture event, plus `$exception` for failed calls. Use it in
+ * `Options(exporters: ['posthog' => new PostHogExporter(apiKey: 'phc_…')])`.
+ */
+final readonly class PostHogExporter
+{
+    /**
+     * @param string      $apiKey          The PostHog project API key (`phc_…`).
+     * @param string|null $host            The PostHog host. Default: null, which uses `https://us.i.posthog.com`.
+     * @param bool        $enableAITracing Also sends a `$ai_span` per tool call; your tags and properties can replace any `$ai_*` value. Default: false.
+     */
+    public function __construct(
+        public string $apiKey,
+        public ?string $host = null,
+        public bool $enableAITracing = false,
+    ) {}
+}

src/Exporters/SentryExporter.php

@@ -0,0 +1,25 @@
+<?php
+
+declare(strict_types=1);
+
+namespace AgentCat\Exporters;
+
+/**
+ * Sends each event to Sentry as a log, optionally a transaction, and an error event for failed calls. Use it in
+ * `Options(exporters: ['sentry' => new SentryExporter(dsn: '…')])`.
+ */
+final readonly class SentryExporter
+{
+    /**
+     * @param string      $dsn           Your project's DSN, `https://<public key>@<host>/<project ID>`. An invalid DSN logs one line and the exporter is skipped.
+     * @param string|null $environment   Added as the `environment` tag of transactions and error events. Default: null (no tag).
+     * @param string|null $release       Added as the `release` tag of transactions and error events. Default: null (no tag).
+     * @param bool        $enableTracing Also sends one transaction per event. Default: false.
+     */
+    public function __construct(
+        public string $dsn,
+        public ?string $environment = null,
+        public ?string $release = null,
+        public bool $enableTracing = false,
+    ) {}
+}

src/Internal/ClientSeams.php

@@ -7,7 +7,7 @@
 use AgentCat\Internal\Delivery\EventQueue;
 
 /**
- * What tests and `AgentCat::fake()` replace in a `Client`: its event queue and its enabled gate. The constructor is
+ * What tests and `AgentCat::fake()` replace in a `Client`: its event queue, its enabled gate and whether it sets up telemetry. The constructor is
  * private, so a dependency-injection container cannot build one, and an autowired `Client` always gets the
  * process-wide queue and the default gate.
  *
@@ -19,11 +19,15 @@
     private function __construct(
         public EventQueue $queue,
         public ?\Closure $enabled,
+        public bool $telemetry,
     ) {}
 
-    /** @param (\Closure(): bool)|null $enabled whether `track()` instruments; null keeps the default gate (D31, D44) */
-    public static function of(EventQueue $queue, ?\Closure $enabled = null): self
+    /**
+     * @param (\Closure(): bool)|null $enabled   whether `track()` instruments; null keeps the default gate (D31, D44)
+     * @param bool                    $telemetry false sets up no exporters and no diagnostics (`AgentCat::fake()`)
+     */
+    public static function of(EventQueue $queue, ?\Closure $enabled = null, bool $telemetry = true): self
     {
-        return new self($queue, $enabled);
+        return new self($queue, $enabled, $telemetry);
     }
 }

src/Internal/Constants.php

@@ -41,4 +41,7 @@ final class Constants
     public const string SOURCE = 'agentcat';
     public const string DIAGNOSTICS_SCOPE_NAME = 'agentcat-diagnostics';
     public const string DEFAULT_API_BASE_URL = 'https://api.agentcat.com';
+    public const string DEFAULT_DIAGNOSTICS_ENDPOINT = 'https://otel.agentcat.com';
+    /** Public by design (TS: a shared ingestion key that deters drive-by traffic; not a secret). */
+    public const string DEFAULT_DIAGNOSTICS_TOKEN = 'dgk_sdk_diag_3f9a2c7e1b8d4065af2e9c1d7b6a4f80';
 }