Overview
Observatory can be configured using environment variables, programmatic configuration, or a combination of both. The SDK automatically handles API key authentication and endpoint routing.
Environment Variables
The following environment variables are supported across all Observatory packages:
Your Observatory API key. Keys starting with dev_ automatically route to the development environment. Custom ingestion endpoint URL. Overrides the default production/development URL selection.TCC_URL=https://api.thecontext.company/v1/custom
- Production:
https://api.thecontext.company/v1/custom
- Development:
https://dev.thecontext.company/v1/custom (when API key starts with dev_)
Enable debug logging to console. Set to 1 or true to activate. Custom feedback endpoint URL for user feedback submission.TCC_FEEDBACK_URL=https://api.thecontext.company/v1/feedback
https://api.thecontext.company/v1/feedback TCC_DISABLE_ANONYMOUS_TELEMETRY
Disable anonymous usage telemetry collection. Set to true to opt out.TCC_DISABLE_ANONYMOUS_TELEMETRY=true
Observatory collects limited anonymous usage data to improve the SDK. No sensitive or personally identifiable information is ever collected. See the telemetry events source code for details. Programmatic Configuration
You can configure Observatory programmatically using the configure() function. This is useful for dynamic configuration or when you prefer code-based settings.
Basic Configuration
import { configure } from "@contextcompany/custom";
configure({
apiKey: "tcc_abc123",
debug: true,
});
Configuration Options
API key for authentication. Overrides TCC_API_KEY environment variable.configure({ apiKey: "tcc_abc123" });
Enable debug logging. Overrides TCC_DEBUG environment variable.configure({ debug: true });
Custom ingestion endpoint. Overrides TCC_URL environment variable.configure({ url: "http://localhost:8787/custom" });
Default auto-flush timeout in milliseconds for all runs. Runs that don’t complete within this duration are automatically flushed with error status.configure({ runTimeout: 600000 }); // 10 minutes
1200000 (20 minutes)Set to 0 to disable auto-flush. Merging Configuration
Multiple calls to configure() are merged together. You only need to pass the fields you want to change.
import { configure } from "@contextcompany/custom";
// Initial configuration
configure({ apiKey: "tcc_abc123" });
// Later, enable debug mode without changing the API key
configure({ debug: true });
// Result: { apiKey: "tcc_abc123", debug: true }
Configuration Priority
When both environment variables and programmatic configuration are present, the following priority order applies:
Programmatic configuration
Settings passed to configure() have the highest priority.
Environment variables
Environment variables are used if no programmatic setting is provided.
Default values
Built-in defaults are used as a fallback.
Example
// Environment: TCC_API_KEY=env_key
configure({ apiKey: "code_key" });
// Result: Uses "code_key" (programmatic config wins)
Framework-Specific Configuration
Next.js with AI SDK
For Next.js applications using the AI SDK integration:
// instrumentation.ts
import { registerOTel } from "@contextcompany/otel/nextjs";
export function register() {
registerOTel();
}
.env.local:
TCC_API_KEY=tcc_abc123
TCC_DEBUG=true
Custom SDK
For custom agents using the manual instrumentation SDK:
import { configure, run } from "@contextcompany/custom";
import { config } from "dotenv";
config(); // Load .env file
configure({
debug: process.env.NODE_ENV === "development",
url: process.env.TCC_URL,
});
const r = run({ sessionId: "session_123" });
// ... instrument your agent
API Key Management
Development vs Production
Observatory automatically routes to the appropriate environment based on your API key prefix:
- Keys starting with
dev_ route to https://dev.thecontext.company
- All other keys route to
https://api.thecontext.company
// Development key - routes to dev environment
configure({ apiKey: "dev_abc123" });
// Production key - routes to production environment
configure({ apiKey: "tcc_abc123" });
Security Best Practices
Never commit API keys to version control. Always use environment variables or secure secret management.
# Good: Environment variable
TCC_API_KEY=tcc_abc123
// Bad: Hardcoded API key
configure({ apiKey: "tcc_abc123" }); // Don't do this!
Missing API Key Handling
If no API key is configured, Observatory logs a warning and skips data transmission:
[TCC] No API key found. Set TCC_API_KEY or call configure({ apiKey }).
Debug Mode
Debug mode outputs detailed logs to help troubleshoot instrumentation:
Example debug output:
[TCC] Run created { "runId": "550e8400-e29b-41d4-a716-446655440000" }
[TCC] Step created { "stepId": "...", "runId": "..." }
[TCC] Sending payload to https://api.thecontext.company/v1/custom
[TCC] Payload: { "type": "run", ... }
[TCC] Payload sent successfully
Enable debug mode during development to verify that instrumentation is working correctly.
Validation
To verify your configuration is working:
Enable debug mode
configure({ debug: true });
Create a test run
const r = run();
r.prompt("test");
await r.end();
Check console output
Look for [TCC] Payload sent successfully in your logs.
Verify in dashboard
Check that the run appears in your Observatory dashboard.
