feat: Otel Observabillity

Author: tymondesigns

composer.json

@@ -23,6 +23,9 @@
         "guzzlehttp/psr7": "^2.8",
         "illuminate/collections": "^12.49",
         "laravel/prompts": "^0.3.8",
+        "open-telemetry/api": "^1.8",
+        "open-telemetry/exporter-otlp": "^1.4",
+        "open-telemetry/sdk": "^1.13",
         "openai-php/client": "^0.18",
         "php-mcp/client": "^1.0",
         "psr-discovery/cache-implementations": "^1.2",
@@ -104,7 +107,8 @@
         "allow-plugins": {
             "dealerdirect/phpcodesniffer-composer-installer": true,
             "pestphp/pest-plugin": true,
-            "php-http/discovery": true
+            "php-http/discovery": true,
+            "tbachert/spi": true
         }
     },
     "extra": {

config/cortex.php

@@ -2,12 +2,13 @@
 
 declare(strict_types=1);
 
+use Cortex\Agents\Prebuilt\WeatherAgent;
 use Cortex\LLM\Enums\LLMDriver;
 use Cortex\LLM\Enums\StreamingProtocol;
-use Cortex\Agents\Prebuilt\WeatherAgent;
-use Cortex\ModelInfo\Providers\OllamaModelInfoProvider;
 use Cortex\ModelInfo\Providers\LiteLLMModelInfoProvider;
 use Cortex\ModelInfo\Providers\LMStudioModelInfoProvider;
+use Cortex\ModelInfo\Providers\OllamaModelInfoProvider;
+use OpenTelemetry\Contrib\Otlp\Protocols;
 
 return [
     /*
@@ -367,4 +368,45 @@
     |
     */
     'default_streaming_protocol' => StreamingProtocol::Vercel,
+
+    /*
+    |--------------------------------------------------------------------------
+    | OpenTelemetry Tracing
+    |--------------------------------------------------------------------------
+    |
+    | Configure OpenTelemetry tracing to export spans for agent runs, LLM calls,
+    | tool executions, and agent steps to any OTLP-compatible backend
+    | (e.g. Jaeger, Grafana Tempo, Honeycomb, Datadog).
+    |
+    | Set CORTEX_TRACING_ENABLED=true and point OTEL_EXPORTER_OTLP_ENDPOINT
+    | at your collector or backend to get started.
+    |
+    */
+    'tracing' => [
+        'enabled' => env('CORTEX_TRACING_ENABLED', true),
+
+        'exporter' => [
+            /**
+             * The OTLP endpoint to export spans to.
+             * For HTTP/protobuf (default): http://localhost:4318/v1/traces
+             * For gRPC: http://localhost:4317
+             */
+            'endpoint' => env('OTEL_EXPORTER_OTLP_ENDPOINT', 'http://localhost:4318/v1/traces'),
+
+            /**
+             * Supported: "http/protobuf", "http/json"
+             */
+            'protocol' => env('OTEL_EXPORTER_OTLP_PROTOCOL', Protocols::HTTP_PROTOBUF),
+
+            /**
+             * The headers to send with the request. Comma separated list of key=value pairs.
+             */
+            'headers' => env('OTEL_EXPORTER_OTLP_HEADERS', ''),
+        ],
+
+        /**
+         * The service name reported to the tracing backend.
+         */
+        'service_name' => env('OTEL_SERVICE_NAME', 'cortex'),
+    ],
 ];

src/CortexServiceProvider.php

@@ -5,25 +5,32 @@
 namespace Cortex;
 
 use Throwable;
-use Monolog\Logger;
 use Cortex\LLM\LLMManager;
 use Cortex\Agents\Registry;
 use Cortex\Console\AgentChat;
 use Cortex\LLM\Contracts\LLM;
 use Cortex\Mcp\McpServerManager;
-use Monolog\Handler\StreamHandler;
-use Monolog\Formatter\LineFormatter;
 use Illuminate\Support\Facades\Blade;
 use Cortex\ModelInfo\ModelInfoFactory;
 use Spatie\LaravelPackageTools\Package;
 use Cortex\Embeddings\EmbeddingsManager;
 use Cortex\Prompts\PromptFactoryManager;
+use OpenTelemetry\Contrib\Otlp\Protocols;
 use Cortex\Embeddings\Contracts\Embeddings;
 use Cortex\Prompts\Contracts\PromptFactory;
+use OpenTelemetry\Contrib\Otlp\SpanExporter;
+use OpenTelemetry\SDK\Resource\ResourceInfo;
 use Illuminate\Contracts\Container\Container;
 use Cortex\Support\Events\InternalEventDispatcher;
+use OpenTelemetry\SDK\Common\Attribute\Attributes;
+use OpenTelemetry\SDK\Common\Util\ShutdownHandler;
+use OpenTelemetry\SDK\Trace\TracerProviderBuilder;
+use OpenTelemetry\SDK\Resource\ResourceInfoFactory;
 use Spatie\LaravelPackageTools\PackageServiceProvider;
-use Cortex\Support\Events\Subscribers\LoggingSubscriber;
+use OpenTelemetry\SemConv\Attributes\ServiceAttributes;
+use OpenTelemetry\Contrib\Otlp\OtlpHttpTransportFactory;
+use Cortex\Support\Events\Subscribers\OpenTelemetrySubscriber;
+use OpenTelemetry\SDK\Trace\SpanProcessor\SimpleSpanProcessor;
 
 class CortexServiceProvider extends PackageServiceProvider
 {
@@ -55,6 +62,7 @@ public function packageBooted(): void
         $this->registerBladeDirectives();
 
         $this->setupLogging();
+        $this->setupTracing();
     }
 
     protected function registerBladeDirectives(): void
@@ -163,12 +171,64 @@ protected function setupLogging(): void
         }
 
         // TODO: This will be configurable.
-        $logger = new Logger('cortex');
-        $handler = new StreamHandler('php://stdout');
-        $handler->setFormatter(new LineFormatter());
+        // $logger = new Logger('cortex');
+        // $handler = new StreamHandler('php://stdout');
+        // $handler->setFormatter(new LineFormatter());
 
-        $logger->pushHandler($handler);
+        // $logger->pushHandler($handler);
 
-        InternalEventDispatcher::instance()->subscribe(new LoggingSubscriber($logger));
+        // InternalEventDispatcher::instance()->subscribe(new LoggingSubscriber($logger));
+    }
+
+    protected function setupTracing(): void
+    {
+        if ($this->app->runningUnitTests()) {
+            return;
+        }
+
+        if (! config('cortex.tracing.enabled', false)) {
+            return;
+        }
+
+        $endpoint = (string) config('cortex.tracing.exporter.endpoint', 'http://localhost:4318/v1/traces');
+        $protocol = (string) config('cortex.tracing.exporter.protocol', Protocols::HTTP_PROTOBUF);
+        $serviceName = (string) config('cortex.tracing.service_name', 'cortex');
+        $rawHeaders = config('cortex.tracing.exporter.headers', '');
+        $headers = [];
+
+        foreach (explode(',', $rawHeaders) as $header) {
+            $header = trim($header);
+            if ($header === '') {
+                continue;
+            }
+            $parts = explode('=', $header, 2);
+            if (count($parts) === 2) {
+                [$key, $value] = $parts;
+                $headers[trim($key)] = trim($value, " \t\n\r\0\x0B\"'");
+            }
+        }
+
+        $resource = ResourceInfoFactory::emptyResource()->merge(
+            ResourceInfo::create(Attributes::create([
+                ServiceAttributes::SERVICE_NAME => $serviceName,
+            ])),
+        );
+
+        $transport = new OtlpHttpTransportFactory()->create(
+            $endpoint,
+            Protocols::contentType($protocol),
+            $headers,
+        );
+
+        $exporter = new SpanExporter($transport);
+
+        $tracerProvider = new TracerProviderBuilder()
+            ->addSpanProcessor(new SimpleSpanProcessor($exporter))
+            ->setResource($resource)
+            ->build();
+
+        ShutdownHandler::register($tracerProvider->shutdown(...));
+
+        InternalEventDispatcher::instance()->subscribe(new OpenTelemetrySubscriber($tracerProvider));
     }
 }

src/LLM/AbstractLLM.php

@@ -412,6 +412,11 @@ public function getMaxTokens(): ?int
         return $this->maxTokens;
     }
 
+    public function getToolConfig(): ?ToolConfig
+    {
+        return $this->toolConfig;
+    }
+
     public function isStreaming(): bool
     {
         return $this->streaming;

src/LLM/Contracts/LLM.php

@@ -6,16 +6,17 @@
 
 use Closure;
 use Cortex\Contracts\Pipeable;
+use Cortex\JsonSchema\Types\ObjectSchema;
 use Cortex\LLM\Data\ChatResult;
+use Cortex\LLM\Data\ChatStreamResult;
+use Cortex\LLM\Data\Messages\MessageCollection;
+use Cortex\LLM\Data\StructuredOutputConfig;
+use Cortex\LLM\Data\ToolConfig;
+use Cortex\LLM\Enums\StructuredOutputMode;
 use Cortex\LLM\Enums\ToolChoice;
 use Cortex\ModelInfo\Data\ModelInfo;
-use Cortex\LLM\Data\ChatStreamResult;
 use Cortex\ModelInfo\Enums\ModelFeature;
-use Cortex\JsonSchema\Types\ObjectSchema;
 use Cortex\ModelInfo\Enums\ModelProvider;
-use Cortex\LLM\Enums\StructuredOutputMode;
-use Cortex\LLM\Data\StructuredOutputConfig;
-use Cortex\LLM\Data\Messages\MessageCollection;
 
 interface LLM extends Pipeable
 {
@@ -192,6 +193,11 @@ public function getStructuredOutputConfig(): ?StructuredOutputConfig;
      */
     public function getStructuredOutputMode(): StructuredOutputMode;
 
+    /**
+     * Get the tool config for the LLM.
+     */
+    public function getToolConfig(): ?ToolConfig;
+
     /**
      * Set whether the raw provider response should be included in the result, if available.
      */