maximhq · akshaydeo · Sep 17, 2025 · Sep 13, 2025
diff --git a/docs/docs.json b/docs/docs.json
@@ -91,6 +91,7 @@
               "features/mcp",
               "features/tracing",
               "features/telemetry",
+              "features/observability",
               "features/governance",
               "features/semantic-caching",
               "features/custom-providers",

diff --git a/docs/features/mcp.mdx b/docs/features/mcp.mdx
@@ -103,7 +103,7 @@ func main() {
         },
     }
 
-    client, err := bifrost.Init(schemas.BifrostConfig{
+    client, err := bifrost.Init(context.Background(), schemas.BifrostConfig{
         Account:   account,
         MCPConfig: mcpConfig,
         Logger:    bifrost.NewDefaultLogger(schemas.LogLevelInfo),
@@ -282,7 +282,7 @@ import (
 
 func main() {
     // Initialize Bifrost with MCP
-    client, err := bifrost.Init(schemas.BifrostConfig{
+    client, err := bifrost.Init(context.Background(), schemas.BifrostConfig{
         Account: account,
         MCPConfig: &schemas.MCPConfig{
             ClientConfigs: []schemas.MCPClientConfig{
@@ -539,7 +539,7 @@ func calculatorHandler(args CalculatorArgs) (string, error) {
 
 func main() {
     // Initialize Bifrost (tool registry creates in-process MCP automatically)
-    client, err := bifrost.Init(schemas.BifrostConfig{
+    client, err := bifrost.Init(context.Background(), schemas.BifrostConfig{
         Account: account,
         Logger:  bifrost.NewDefaultLogger(schemas.LogLevelInfo),
     })

diff --git a/docs/features/observability.mdx b/docs/features/observability.mdx
@@ -1,6 +1,229 @@
 ---
 title: "Observability"
-description: "Comprehensive Prometheus-based monitoring for Bifrost Gateway with custom metrics and labels."
+description: "Integrate Maxim SDK for comprehensive LLM observability, tracing, and evaluation."
 icon: "binoculars"
 ---
 
+## Overview
+
+Bifrost provides comprehensive LLM observability through the **Maxim plugin**, enabling seamless tracking, evaluation, and analysis of AI interactions. The plugin automatically forwards all LLM requests and responses to Maxim's platform for detailed monitoring and performance insights.
+
+![Maxim Logs](../media/maxim-logs.png)
+
+---
+
+## Setup
+
+The Maxim plugin enables seamless observability and evaluation of LLM interactions by forwarding inputs/outputs to Maxim's platform:
+
+<Tabs group="setup-method">
+<Tab title="Go SDK">
+
+```go
+package main
+
+import (
+    "context"
+    bifrost "github.com/maximhq/bifrost/core"
+    "github.com/maximhq/bifrost/core/schemas"
+    maxim "github.com/maximhq/bifrost/plugins/maxim"
+)
+
+func main() {
+    // Initialize Maxim plugin
+    maximPlugin, err := maxim.Init(maxim.Config{
+        ApiKey:    "your_maxim_api_key",
+        LogRepoId: "your_default_repo_id", // Optional: fallback repository
+    })
+    if err != nil {
+        panic(err)
+    }
+
+    // Initialize Bifrost with the plugin
+    client, err := bifrost.Init(context.Background(), schemas.BifrostConfig{
+        Account: &yourAccount,
+        Plugins: []schemas.Plugin{maximPlugin},
+    })
+    if err != nil {
+        panic(err)
+    }
+    defer client.Shutdown()
+
+    // All requests will now be traced to Maxim
+}
+```
+
+</Tab>
+<Tab title="config.json">
+
+For HTTP transport, configure via environment variables:
+
+```json
+{
+  "plugins": [
+    {
+      "enabled": true,
+      "name": "maxim",
+      "config": {        
+        "api_key": "your_maxim_api_key",
+        "log_repo_id": "your_default_repo_id"
+      }
+    }
+  ]
+}
+```
+
+</Tab>
+</Tabs>
+
+## Configuration
+
+### Plugin Configuration
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `ApiKey` | `string` | ✅ Yes | Your Maxim API key for authentication |
+| `LogRepoId` | `string` | ❌ No | Default log repository ID (can be overridden per request) |
+
+## Repository Selection
+
+The plugin uses repository selection with the following priority:
+
+1. **Header/Context Repository** - Highest priority
+2. **Default Repository** (from plugin config) - Fallback
+3. **Skip Logging** - If neither is available
+
+<Tabs group="repository-selection"  >
+<Tab title="Go SDK">
+
+```go
+ctx := context.Background()
+
+// Use specific repository for this request
+ctx = context.WithValue(ctx, maxim.LogRepoIDKey, "project-specific-repo")
+```
+
+</Tab>
+<Tab title="Gateway"> 
+
+```bash
+# Use default repository (from config)
+curl -X POST http://localhost:8080/v1/chat/completions \
+  -d '{"model": "gpt-4", "messages": [...]}'
+
+# Override with specific repository
+curl -X POST http://localhost:8080/v1/chat/completions \
+  -H "x-bf-maxim-log-repo-id: project-specific-repo" \
+  -d '{"model": "gpt-4", "messages": [...]}'
+```
+
+</Tab>
+</Tabs>
+
+
+## Custom Trace Management
+
+### Trace Propagation
+
+The plugin supports custom session, trace, and generation IDs for advanced tracing scenarios:
+
+<Tabs group="trace-propagation">
+<Tab title="Go SDK">
+```go
+ctx := context.Background()
+
+// Prefer typed keys from the Maxim plugin
+ctx = context.WithValue(ctx, maxim.TraceIDKey, "custom-trace-123")
+ctx = context.WithValue(ctx, maxim.GenerationIDKey, "custom-gen-456")
+ctx = context.WithValue(ctx, maxim.SessionIDKey, "user-session-789")
+
+// Optionally set human-friendly names
+ctx = context.WithValue(ctx, maxim.TraceNameKey, "checkout-flow")
+ctx = context.WithValue(ctx, maxim.GenerationNameKey, "rerank-step")
+```
+</Tab>
+<Tab title="Gateway">
+```bash
+curl -X POST http://localhost:8080/v1/chat/completions \
+  -H "x-bf-maxim-trace-id: custom-trace-123" \
+  -H "x-bf-maxim-generation-id: custom-gen-456" \
+  -H "x-bf-maxim-session-id: user-session-789" \
+  -H "x-bf-maxim-trace-name: checkout-flow" \
+  -H "x-bf-maxim-generation-name: rerank-step" \
+  -d '{"model": "gpt-4", "messages": [...]}'
+```
+</Tab>
+</Tabs>
+
+### Custom Tags
+
+You can add custom tags to traces for enhanced filtering and analytics:
+
+<Tabs group="custom-tags">
+<Tab title="Go SDK">
+
+```go
+ctx := context.Background()
+
+// Pass arbitrary tag key-values via context map
+tags := map[string]string{
+    "environment":  "production",
+    "user-id":      "user-123",
+    "feature-flag": "new-ui",
+}
+ctx = context.WithValue(ctx, maxim.TagsKey, tags)
+```
+
+</Tab>
+<Tab title="Gateway">
+
+```bash
+curl -X POST http://localhost:8080/v1/chat/completions \
+  -H "x-bf-maxim-environment: production" \
+  -H "x-bf-maxim-user-id: user-123" \
+  -H "x-bf-maxim-feature-flag: new-ui" \
+  -d '{"model": "gpt-4", "messages": [...]}'
+```
+
+Reserved keys are `session-id`, `trace-id`, `trace-name`, `generation-id`, `generation-name`, `log-repo-id`. All other `x-bf-maxim-*` headers are treated as tags.
+
+</Tab>
+</Tabs>
+
+## Supported Request Types
+
+The plugin supports the following Bifrost request types:
+
+| Request Type | Support | Logged Data |
+|--------------|---------|-------------|
+| **Chat Completion** | ✅ Full | Messages, model parameters, responses |
+| **Text Completion** | ✅ Full | Input text, model parameters, responses |
+
+## Monitoring & Analytics
+
+### Maxim Dashboard
+
+Once configured, view your traces at [Maxim Dashboard](https://getmaxim.ai/):
+
+- **Request/Response Tracking**: Complete LLM interaction logs
+- **Performance Metrics**: Latency, token usage, and cost analytics
+- **Tool Usage Patterns**: Function calling and tool interaction insights
+- **Error Tracking**: Detailed error logs and failure analysis
+
+### Key Metrics
+
+- **Trace Coverage**: Percentage of requests being logged
+- **Response Times**: End-to-end latency tracking
+- **Token Usage**: Input/output token consumption
+- **Cost Analytics**: Per-request and aggregate cost tracking
+ - **Cost Analytics**: Per-request and aggregate cost tracking
+
+----
+
+## Next Steps
+
+Now that you have observability set up with the Maxim plugin, explore these related topics:
+
+- **[Tracing](./tracing)** - Deep-dive into request/response logging and correlation
+- **[Telemetry](./telemetry)** - Prometheus metrics, dashboards, and alerting
+- **[Governance](./governance)** - Virtual keys, per-team controls, and usage limits
diff --git a/docs/features/plugins/jsonparser.mdx b/docs/features/plugins/jsonparser.mdx
@@ -46,7 +46,7 @@ func main() {
     })
 
     // Initialize Bifrost with the plugin
-    client, err := bifrost.Init(schemas.BifrostConfig{
+    client, err := bifrost.Init(context.Background(), schemas.BifrostConfig{
         Account: &MyAccount{},
         Plugins: []schemas.Plugin{
             jsonPlugin,
@@ -84,7 +84,7 @@ func main() {
     })
 
     // Initialize Bifrost with the plugin
-    client, err := bifrost.Init(schemas.BifrostConfig{
+    client, err := bifrost.Init(context.Background(), schemas.BifrostConfig{
         Account: &MyAccount{},
         Plugins: []schemas.Plugin{
             jsonPlugin,
@@ -201,7 +201,7 @@ func main() {
     })
 
     // Initialize Bifrost with the plugin
-    client, err := bifrost.Init(schemas.BifrostConfig{
+    client, err := bifrost.Init(context.Background(), schemas.BifrostConfig{
         Account: &MyAccount{},
         Plugins: []schemas.Plugin{jsonPlugin},
     })

diff --git a/docs/features/plugins/mocker.mdx b/docs/features/plugins/mocker.mdx
@@ -30,7 +30,7 @@ func main() {
     }
 
     // Initialize Bifrost with the plugin
-    client, initErr := bifrost.Init(schemas.BifrostConfig{
+    client, initErr := bifrost.Init(context.Background(), schemas.BifrostConfig{
         Account: &yourAccount,
         Plugins: []schemas.Plugin{plugin},
     })
@@ -124,7 +124,7 @@ if err != nil {
 ### Adding to Bifrost
 
 ```go
-client, initErr := bifrost.Init(schemas.BifrostConfig{
+client, initErr := bifrost.Init(context.Background(), schemas.BifrostConfig{
     Account: &yourAccount,
     Plugins: []schemas.Plugin{plugin},
     Logger: bifrost.NewDefaultLogger(schemas.LogLevelInfo),
@@ -476,7 +476,7 @@ Response{
 Enable debug logging to troubleshoot:
 
 ```go
-client, initErr := bifrost.Init(schemas.BifrostConfig{
+client, initErr := bifrost.Init(context.Background(), schemas.BifrostConfig{
     Account: &account,
     Plugins: []schemas.Plugin{plugin},
     Logger:  bifrost.NewDefaultLogger(schemas.LogLevelDebug),

diff --git a/docs/media/maxim-logs.png b/docs/media/maxim-logs.png
diff --git a/docs/media/ui-observability-config.png b/docs/media/ui-observability-config.png
diff --git a/docs/quickstart/go-sdk/setting-up.mdx b/docs/quickstart/go-sdk/setting-up.mdx
@@ -72,7 +72,7 @@ func (a *MyAccount) GetConfigForProvider(provider schemas.ModelProvider) (*schem
 
 // Main function implement to initialize bifrost and make a request
 func main() {
-	client, initErr := bifrost.Init(schemas.BifrostConfig{
+	client, initErr := bifrost.Init(context.Background(), schemas.BifrostConfig{
 		Account: &MyAccount{},
 	})
 	if initErr != nil {

diff --git a/docs/quickstart/go-sdk/tool-calling.mdx b/docs/quickstart/go-sdk/tool-calling.mdx
@@ -73,7 +73,7 @@ if toolCalls != nil {
 Connect to Model Context Protocol (MCP) servers to give AI models access to external tools and services without manually defining each function.
 
 ```go
-client, initErr := bifrost.Init(schemas.BifrostConfig{
+client, initErr := bifrost.Init(context.Background(), schemas.BifrostConfig{
 	Account: &MyAccount{},
 	MCPConfig: &schemas.MCPConfig{
 		ClientConfigs: []schemas.MCPClientConfig{