# Change an alert Source: https://docs.superlog.sh/api-reference/alerts/change-an-alert /api-reference/openapi.json patch /alerts/{alertId} Changes the fields you send and keeps the rest. `filter` replaces the whole filter. Changing what the alert reads or its threshold, or disabling it, ends its open activations without posting a recovery; the next check opens new ones where the value is still past the threshold. # Create an alert Source: https://docs.superlog.sh/api-reference/alerts/create-an-alert /api-reference/openapi.json post /alerts Creates a threshold alert on logs, spans, or a metric. While the value is past the threshold, the alert posts once to its Slack channel and posts the recovery in the same thread. # Delete an alert Source: https://docs.superlog.sh/api-reference/alerts/delete-an-alert /api-reference/openapi.json delete /alerts/{alertId} Deletes an alert and its activation history. # Get an alert Source: https://docs.superlog.sh/api-reference/alerts/get-an-alert /api-reference/openapi.json get /alerts/{alertId} Returns an alert with its 20 most recent activations. An activation is one period during which the alert, or one of its groups, was past the threshold. # List alerts Source: https://docs.superlog.sh/api-reference/alerts/list-alerts /api-reference/openapi.json get /alerts Lists the workspace's alerts by name, with each one's rule, Slack channel, and how many groups are firing now. # Preview an alert rule Source: https://docs.superlog.sh/api-reference/alerts/preview-an-alert-rule /api-reference/openapi.json post /alerts/preview Reads the current window of a draft rule without saving it, and returns each group's value and whether it is past the threshold, those past it first. Use it to choose a threshold. # List API keys Source: https://docs.superlog.sh/api-reference/api-keys/list-api-keys /api-reference/openapi.json get /api-keys Lists the workspace's active API keys. Create keys in the app under **Settings → API keys**. # Revoke an API key Source: https://docs.superlog.sh/api-reference/api-keys/revoke-an-api-key /api-reference/openapi.json delete /api-keys/{apiKeyId} Revokes an API key. It stops working immediately. Admins and owners can revoke any key; members can revoke only their own. # Create an automation Source: https://docs.superlog.sh/api-reference/automations/create-an-automation /api-reference/openapi.json post /automations Creates an automation. Model settings you leave out use the defaults. # Get an automation Source: https://docs.superlog.sh/api-reference/automations/get-an-automation /api-reference/openapi.json get /automations/{automationId} Returns an automation and its current configuration. # Get an automation's webhook Source: https://docs.superlog.sh/api-reference/automations/get-an-automations-webhook /api-reference/openapi.json get /automations/{automationId}/webhook Returns the URL and bearer token for an automation's webhook trigger. A POST request to the URL with `Authorization: Bearer ` starts a run while the automation is on and has a `webhook` trigger. The request body is the run's trigger payload; a JSON body's `title` names the run. Requests with the same `Idempotency-Key` header start one run. # List automations Source: https://docs.superlog.sh/api-reference/automations/list-automations /api-reference/openapi.json get /automations Lists automations, most recently changed first, with each one's last run. # Update an automation Source: https://docs.superlog.sh/api-reference/automations/update-an-automation /api-reference/openapi.json patch /automations/{automationId} Changes an automation. Send only what changes. In `configuration`, each field you send replaces the current value, and fields you leave out are kept. Changing only `enabled` turns the automation on or off without saving a new version. # Add a widget to a dashboard Source: https://docs.superlog.sh/api-reference/dashboards/add-a-widget-to-a-dashboard /api-reference/openapi.json post /dashboards/{dashboardId}/widgets Adds a chart, table, or text widget to a dashboard. Without a layout, the widget gets the standard size for its type below the others. # Change a dashboard Source: https://docs.superlog.sh/api-reference/dashboards/change-a-dashboard /api-reference/openapi.json patch /dashboards/{dashboardId} Changes a dashboard's name, variables, or widgets. `variables` and `widgets` each replace the whole list, so include everything to keep. Read the dashboard first to get its widget IDs. # Change a dashboard widget Source: https://docs.superlog.sh/api-reference/dashboards/change-a-dashboard-widget /api-reference/openapi.json patch /dashboards/{dashboardId}/widgets/{widgetId} Changes a widget's title, settings, or position. `config` replaces all of the widget's settings, so include every setting to keep. # Create a dashboard Source: https://docs.superlog.sh/api-reference/dashboards/create-a-dashboard /api-reference/openapi.json post /dashboards Creates a dashboard, optionally with variables and widgets. Widgets can also be added to it afterward. # Delete a dashboard Source: https://docs.superlog.sh/api-reference/dashboards/delete-a-dashboard /api-reference/openapi.json delete /dashboards/{dashboardId} Deletes a dashboard and all of its widgets. # Get a dashboard Source: https://docs.superlog.sh/api-reference/dashboards/get-a-dashboard /api-reference/openapi.json get /dashboards/{dashboardId} Returns a dashboard with its variables and every widget's type, settings, and position. # List dashboards Source: https://docs.superlog.sh/api-reference/dashboards/list-dashboards /api-reference/openapi.json get /dashboards Lists the workspace's dashboards, most recently changed first, with how many widgets each has. # Move and resize dashboard widgets Source: https://docs.superlog.sh/api-reference/dashboards/move-and-resize-dashboard-widgets /api-reference/openapi.json patch /dashboards/{dashboardId}/layout Sets the position and size of several widgets on one dashboard at once. Widgets left out keep their place. # Remove a dashboard widget Source: https://docs.superlog.sh/api-reference/dashboards/remove-a-dashboard-widget /api-reference/openapi.json delete /dashboards/{dashboardId}/widgets/{widgetId} Removes one widget from a dashboard. # Get an error issue Source: https://docs.superlog.sh/api-reference/errors/get-an-error-issue /api-reference/openapi.json get /error-issues/{issueId} Returns an error issue with its newest occurrence, including the stack trace, and its occurrences per day. # Get error notifications Source: https://docs.superlog.sh/api-reference/errors/get-error-notifications /api-reference/openapi.json get /error-notifications Returns whether new and regressed error issues post to Slack, and to which channel. Workspace owners and admins only. # List error issues Source: https://docs.superlog.sh/api-reference/errors/list-error-issues /api-reference/openapi.json get /error-issues Lists the workspace's error issues, most recently seen first. Each issue groups exceptions with the same type, normalized message, and application frames. # Resolve, silence, or reopen an error issue Source: https://docs.superlog.sh/api-reference/errors/resolve-silence-or-reopen-an-error-issue /api-reference/openapi.json patch /error-issues/{issueId} Sets an error issue's status. A resolved issue opens again when it occurs after being resolved; a silenced issue only counts its occurrences. # Turn error notifications on or off Source: https://docs.superlog.sh/api-reference/errors/turn-error-notifications-on-or-off /api-reference/openapi.json patch /error-notifications Posts each new error issue, and each resolved issue that occurs again, to one Slack channel. For a private channel, invite the Superlog app first. Earlier errors are not posted. Workspace owners and admins only. # Find integrations to connect Source: https://docs.superlog.sh/api-reference/integrations/find-integrations-to-connect /api-reference/openapi.json get /integrations/available Lists the integrations this server can connect and whether each one uses a provider consent link or secure setup in Superlog. It does not show which integrations are connected. # Get an integration consent link Source: https://docs.superlog.sh/api-reference/integrations/get-an-integration-consent-link /api-reference/openapi.json post /integrations/connect Starts connecting one integration to the workspace. For OAuth providers, returns a consent link that is personal to the signed-in person and workspace and expires after ten minutes, or status `connected` when an existing connection is recovered. A new connection completes after the person approves access in a browser signed in to the same Superlog account and workspace. For integrations that need credentials or extra setup, returns a link to secure setup in Superlog. # List integrations Source: https://docs.superlog.sh/api-reference/integrations/list-integrations /api-reference/openapi.json get /integrations Lists connected integrations, the repositories they give access to, and their resources, such as Slack channels and Sentry projects. # List Sentry environments Source: https://docs.superlog.sh/api-reference/integrations/list-sentry-environments /api-reference/openapi.json get /integrations/{integrationAccountId}/sentry-environments Lists the environments of a Sentry connection, for a Sentry trigger's `excludedEnvironments`. # List Slack channels for alerts Source: https://docs.superlog.sh/api-reference/integrations/list-slack-channels-for-alerts /api-reference/openapi.json get /slack-channels Lists the Slack channels alerts and synthetic checks can post to: public channels, and private channels the Superlog app is in. # Refresh repositories or channels Source: https://docs.superlog.sh/api-reference/integrations/refresh-repositories-or-channels /api-reference/openapi.json post /integrations/refresh Reloads GitHub repositories or Slack channels from the provider, then returns the same result as listing integrations. Use it after giving the GitHub App access to a new repository or creating a Slack channel. # Management API Source: https://docs.superlog.sh/api-reference/introduction Manage automations, runs, tag mode, model access, secrets, dashboards, alerts, and synthetic checks over HTTP. The management API lets scripts, CI jobs, and agents do what you do in **Settings**, **Automations**, and **Tag mode**: create and change automations, start and follow runs, change tag mode, and manage model keys and workspace secrets. It also reads the workspace's logs, traces, metrics, and errors, and manages dashboards, alerts, and synthetic checks. The same operations are available as tools in the [Superlog MCP server](/api-reference/mcp). ## Base URL ```text theme={null} https://superlog.sh/api/v1 ``` A self-hosted deployment serves the API at `/api/v1` on its own origin. ## Authentication Send a workspace API key as a bearer token: ```bash theme={null} curl https://superlog.sh/api/v1/workspace \ -H "Authorization: Bearer $SUPERLOG_API_KEY" ``` Create keys under **Settings → API keys**. See [API keys](/settings/api-keys). A key belongs to one workspace and acts as the member who created it. Changes made with the key are recorded under that member's name. The key stops working when it is revoked or when that member leaves the workspace. ## Find the IDs you need Automations and tag mode refer to repositories, integrations, channels, and secrets by ID. Look them up first: * `GET /integrations` returns connected integrations, the repositories GitHub gives access to, and integration resources such as Slack channels and Sentry projects. * `GET /secrets` returns workspace secrets. Integrations are connected in the app. After you give the GitHub App access to a new repository or create a Slack channel, call `POST /integrations/refresh` to load it. ## Create an automation ```bash theme={null} curl https://superlog.sh/api/v1/automations \ -H "Authorization: Bearer $SUPERLOG_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Weekly dependency review", "configuration": { "prompt": "Review outdated dependencies and open a pull request for safe upgrades.", "repositoryIds": ["f458cf4e-7e6f-452c-8da6-3187a35c1f10"], "triggers": [ { "kind": "schedule", "frequency": "weekly", "hour": 9, "weekday": 1, "timezone": "Europe/Paris" } ] } }' ``` Model settings you leave out use the defaults: the Codex harness with `gpt-5.4`. See [Models and harnesses](/automations/models). ## Change part of an automation `PATCH` requests change only the fields you send. In `configuration`, each field you send replaces the current value, and a list you send replaces the whole list. ```bash theme={null} curl -X PATCH https://superlog.sh/api/v1/automations/$AUTOMATION_ID \ -H "Authorization: Bearer $SUPERLOG_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "configuration": { "prompt": "Also check for security advisories." } }' ``` Send only `enabled` to turn an automation on or off. `PATCH /tag-mode` works the same way. ## Start and follow a run `POST /automations/{automationId}/runs` starts a run and returns its `runId`. Add a `message` to start the run as a chat. Poll `GET /runs/{runId}` until `status` is `succeeded`, `failed`, or `cancelled`. `resultSummary` holds the agent's final answer, and `events` holds the transcript. Send a follow-up with `POST /runs/{runId}/messages` once the run has finished. ## Manage dashboards, alerts, and checks with Terraform The [`superloglabs/superlog`](https://registry.terraform.io/providers/superloglabs/superlog/latest) Terraform provider manages alerts, dashboards, and synthetic checks through this API. It also works with OpenTofu. `GET /terraform` returns provider configuration for the objects you already have, with an `import` block for each one. Applying it adopts the existing objects instead of creating copies: ```bash theme={null} curl https://superlog.sh/api/v1/terraform \ -H "Authorization: Bearer $SUPERLOG_API_KEY" | jq -r .hcl > superlog.tf terraform init && terraform apply ``` Without parameters it exports everything. Pass `alertIds`, `dashboardIds`, or `syntheticCheckIds` as comma-separated IDs to export only those. Secret header values of synthetic checks become sensitive variables for you to set. **Copy as Terraform** on an alert, dashboard, or synthetic check page copies the same configuration for one object. ## Errors Errors return a JSON body with a message and, when there is one, a stable `code`: ```json theme={null} { "code": "invalid_request", "error": "Invalid request", "issues": [{ "message": "Invalid UUID", "path": ["automationId"] }] } ``` | Status | Meaning | | - | - | | `400` | The request is invalid. `issues` lists each invalid field. | | `401` | The API key is missing, revoked, or its member left the workspace. | | `404` | The resource is not in this workspace, or its feature, such as automations or alerts, is not enabled for it. | | `409` | The request conflicts with the current state, such as a name already in use or a run that is still active. | | `502`, `503` | A provider or the run queue is unavailable. Try again. | ## What stays in the app Connecting integrations, inviting and removing members, billing, creating API keys, and connecting a ChatGPT subscription are done in the app. # MCP server Source: https://docs.superlog.sh/api-reference/mcp Let Claude, Cursor, Codex, and other MCP clients manage your Superlog workspace. The Superlog MCP server gives an AI assistant the [management API](/api-reference/introduction) as tools. Ask it to create an automation, change tag mode, start a run, or check why a run failed. ## Server details | | | | - | - | | URL | `https://superlog.sh/api/mcp` | | Transport | Streamable HTTP | | Authentication | OAuth sign-in, or `Authorization: Bearer ` | Clients that support MCP OAuth sign you in through Superlog. You choose a workspace and approve access, and the assistant acts as you in that workspace. For clients without OAuth, create an API key under **Settings → API keys** and send it as a bearer token. See [API keys](/settings/api-keys). The assistant acts as the member who created the key. ## Connect a client **Claude Code** Install the Superlog plugin, then run `/mcp` and sign in: ```bash theme={null} claude plugin marketplace add superloglabs/claude-plugin claude plugin install superlog@superlog ``` See [Claude](/assistants/claude) for the Claude apps and other options. **Cursor** Add the server to `~/.cursor/mcp.json`, or to `.cursor/mcp.json` in a project: ```json theme={null} { "mcpServers": { "superlog": { "url": "https://superlog.sh/api/mcp", "headers": { "Authorization": "Bearer slk_..." } } } } ``` **Codex** Add the server to `~/.codex/config.toml` and set `SUPERLOG_API_KEY` in your environment: ```toml theme={null} [mcp_servers.superlog] url = "https://superlog.sh/api/mcp" bearer_token_env_var = "SUPERLOG_API_KEY" ``` **VS Code** Add the server to `.vscode/mcp.json`. VS Code asks for the key the first time it starts the server: ```json theme={null} { "inputs": [ { "type": "promptString", "id": "superlog-key", "description": "Superlog API key", "password": true } ], "servers": { "superlog": { "type": "http", "url": "https://superlog.sh/api/mcp", "headers": { "Authorization": "Bearer ${input:superlog-key}" } } } } ``` ## Tools | Area | Tools | | - | - | | Workspace | `get_workspace`, `list_members` | | Integrations | `list_available_integrations`, `start_integration_connection`, `list_integrations`, `refresh_integrations`, `list_sentry_environments` | | Automations | `list_automations`, `get_automation`, `create_automation`, `update_automation` | | Runs | `list_automation_runs`, `start_automation_run`, `get_automation_run`, `cancel_automation_run`, `send_automation_run_message` | | Tag mode | `get_tag_mode`, `update_tag_mode` | | Models | `list_included_models`, `list_model_credentials`, `list_model_credential_models`, `test_model_credential`, `delete_model_credential` | | Secrets | `list_secrets` | | API keys | `list_api_keys`, `revoke_api_key` | | Telemetry | `list_services`, `query_logs`, `query_traces`, `query_metrics`, `get_trace`, `list_ingest_keys`, `create_ingest_key` | | Errors | `list_error_issues`, `get_error_issue`, `update_error_issue`, `get_error_notifications`, `update_error_notifications` | | Dashboards | `list_dashboards`, `get_dashboard`, `create_dashboard`, `update_dashboard`, `delete_dashboard`, `add_dashboard_widget`, `update_dashboard_widget`, `delete_dashboard_widget`, `update_dashboard_layout` | | Alerts | `list_alerts`, `get_alert`, `preview_alert`, `create_alert`, `update_alert`, `delete_alert`, `list_slack_channels` | | Synthetics | `list_synthetic_checks`, `get_synthetic_check`, `create_synthetic_check`, `update_synthetic_check`, `delete_synthetic_check` | | Terraform | `export_terraform` | Each tool takes the same fields as its API endpoint. Read-only tools are marked as read-only. `update_automation`, `cancel_automation_run`, `update_tag_mode`, `revoke_api_key`, and `delete_model_credential` are marked as destructive, so clients can ask before running them. `start_integration_connection` returns a consent link for the person to open in their browser. Integrations that need a credential return a secure setup link instead, so the credential is entered in Superlog and not in the conversation. The telemetry, error, dashboard, alert, synthetic, and Terraform tools need telemetry, which is in early access. `create_ingest_key` returns the new key once, with the OpenTelemetry settings for it. `get_error_notifications` and `update_error_notifications` are for workspace owners and admins. Adding a workspace secret or a model API key is not available as a tool, so those values never pass through a model. Use the app or the [API](/api-reference/introduction) for them. ## Example requests * "Create an automation that reviews new Sentry regressions in the `api` project and opens a pull request in `acme/api`." * "Turn off the weekly dependency review." * "Why did the last run of the triage automation fail?" * "Let tag mode read the `acme/web` repository." # Add a model API key Source: https://docs.superlog.sh/api-reference/models/add-a-model-api-key /api-reference/openapi.json post /model-credentials Adds a model provider API key. Superlog checks the key with the provider before saving it. Every automation that uses this provider then runs on your key. Connect a ChatGPT subscription in the app. # List a credential's models Source: https://docs.superlog.sh/api-reference/models/list-a-credentials-models /api-reference/openapi.json get /model-credentials/{credentialId}/models Lists the models a model credential can use. # List included models Source: https://docs.superlog.sh/api-reference/models/list-included-models /api-reference/openapi.json get /models Lists the models of one provider that automations can use with the usage included in your plan. # List model credentials Source: https://docs.superlog.sh/api-reference/models/list-model-credentials /api-reference/openapi.json get /model-credentials Lists the workspace's model API keys and ChatGPT subscriptions. Key values are never returned. # Remove a model credential Source: https://docs.superlog.sh/api-reference/models/remove-a-model-credential /api-reference/openapi.json delete /model-credentials/{credentialId} Removes a model credential. Automations that used it fall back to included usage. # Replace a model API key Source: https://docs.superlog.sh/api-reference/models/replace-a-model-api-key /api-reference/openapi.json post /model-credentials/{credentialId}/rotate Replaces the key of a model API key credential, for example after you rotate it with the provider. # Test a model credential Source: https://docs.superlog.sh/api-reference/models/test-a-model-credential /api-reference/openapi.json post /model-credentials/{credentialId}/test Checks that a model credential works and can use a model. The credential's status is updated with the result. # Cancel a run Source: https://docs.superlog.sh/api-reference/runs/cancel-a-run /api-reference/openapi.json post /runs/{runId}/cancel Asks an active run to stop. The run ends as `cancelled`. # Get a run Source: https://docs.superlog.sh/api-reference/runs/get-a-run /api-reference/openapi.json get /runs/{runId} Returns a run with its status, result, usage, and transcript events. # List runs Source: https://docs.superlog.sh/api-reference/runs/list-runs /api-reference/openapi.json get /automations/{automationId}/runs Lists an automation's runs, newest first. # Send a follow-up message Source: https://docs.superlog.sh/api-reference/runs/send-a-follow-up-message /api-reference/openapi.json post /runs/{runId}/messages Sends a follow-up message to a finished run. The agent continues the same conversation in a new turn. # Start a run Source: https://docs.superlog.sh/api-reference/runs/start-a-run /api-reference/openapi.json post /automations/{automationId}/runs Starts a run now. With a `message`, the run starts as a chat: the agent gets the message as its request, and you can continue with follow-up messages. # Create a workspace secret Source: https://docs.superlog.sh/api-reference/secrets/create-a-workspace-secret /api-reference/openapi.json post /secrets Stores a workspace secret. Agents see the environment variable `name` with a placeholder value, and Superlog substitutes the real value only in requests to the allowed hosts. The value cannot be read back. # List workspace secrets Source: https://docs.superlog.sh/api-reference/secrets/list-workspace-secrets /api-reference/openapi.json get /secrets Lists workspace secrets. Secret values are never returned. # Change a synthetic check Source: https://docs.superlog.sh/api-reference/synthetics/change-a-synthetic-check /api-reference/openapi.json patch /synthetic-checks/{checkId} Changes the fields you send and keeps the rest. `headers` and `assertions` each replace the whole list. Changing the request or assertions, or disabling the check, ends its open failure without posting a recovery. # Create a synthetic check Source: https://docs.superlog.sh/api-reference/synthetics/create-a-synthetic-check /api-reference/openapi.json post /synthetic-checks Creates a check that requests a URL on a schedule and checks the response. After `failuresToAlert` failed runs in a row it posts to its Slack channel, and posts the recovery in the same thread. Defaults: GET, every 300 seconds, a 10 second timeout, 1 retry, alert after 1 failure, follow redirects, enabled. # Delete a synthetic check Source: https://docs.superlog.sh/api-reference/synthetics/delete-a-synthetic-check /api-reference/openapi.json delete /synthetic-checks/{checkId} Deletes a synthetic check and its run history. # Get a synthetic check Source: https://docs.superlog.sh/api-reference/synthetics/get-a-synthetic-check /api-reference/openapi.json get /synthetic-checks/{checkId} Returns a synthetic check. Secret header values are not returned. # List synthetic checks Source: https://docs.superlog.sh/api-reference/synthetics/list-synthetic-checks /api-reference/openapi.json get /synthetic-checks Lists the workspace's synthetic checks by name, with each one's request, assertions, last status, and uptime over the last day. # Get tag mode Source: https://docs.superlog.sh/api-reference/tag-mode/get-tag-mode /api-reference/openapi.json get /tag-mode Returns tag mode settings: whether Slack mentions get answers, the prompt, and the repositories, integrations, and secrets it can use. Null when tag mode has never been set up. # Update tag mode Source: https://docs.superlog.sh/api-reference/tag-mode/update-tag-mode /api-reference/openapi.json patch /tag-mode Changes tag mode. Send only what changes; each list you send replaces the current selection. The first change starts tag mode on, with every connected context integration. Tag mode needs a Slack connection. # Create an ingest key Source: https://docs.superlog.sh/api-reference/telemetry/create-an-ingest-key /api-reference/openapi.json post /ingest-keys Creates a key that applications send logs, traces, and metrics with, and returns its value once. The key can only add telemetry to this workspace. Put it in the app's environment or secret manager, never in a committed file. Browser apps may embed it. # Get a trace Source: https://docs.superlog.sh/api-reference/telemetry/get-a-trace /api-reference/openapi.json get /telemetry/traces/{traceId} Returns every span of one trace in start order, and the logs written during it. # List ingest keys Source: https://docs.superlog.sh/api-reference/telemetry/list-ingest-keys /api-reference/openapi.json get /ingest-keys Lists the workspace's ingest keys, newest first, with when each one last sent telemetry. Key values are not returned. # List services Source: https://docs.superlog.sh/api-reference/telemetry/list-services /api-reference/openapi.json get /telemetry/services Lists the services that sent logs, traces, or metrics in a time window. # Read metric points Source: https://docs.superlog.sh/api-reference/telemetry/read-metric-points /api-reference/openapi.json post /telemetry/metrics/search Returns the workspace's recent OpenTelemetry metric points in a time window, newest first, across gauges, sums, histograms, and summaries. Gauge and sum points carry a `value`; histogram and summary points carry `count` and `sum` instead. # Search logs Source: https://docs.superlog.sh/api-reference/telemetry/search-logs /api-reference/openapi.json post /telemetry/logs/search Returns the workspace's OpenTelemetry logs in a time window, newest first. Error logs include the recorded exception type, message, and stack trace. # Search spans Source: https://docs.superlog.sh/api-reference/telemetry/search-spans /api-reference/openapi.json post /telemetry/traces/search Returns the workspace's OpenTelemetry spans in a time window, newest first. Spans that recorded an exception include its type, message, and stack trace. # Export to Terraform Source: https://docs.superlog.sh/api-reference/terraform/export-to-terraform /api-reference/openapi.json get /terraform Returns Terraform configuration for the superloglabs/superlog provider that describes the workspace's alerts, dashboards, and synthetic checks, with an import block for each one, so applying it adopts the existing objects instead of creating copies. Without IDs it exports everything; with IDs it exports only those. Secret header values become sensitive variables to fill in. # Get the workspace Source: https://docs.superlog.sh/api-reference/workspace/get-the-workspace /api-reference/openapi.json get /workspace Returns the workspace, its enabled features, and the member the caller acts as. # List members Source: https://docs.superlog.sh/api-reference/workspace/list-members /api-reference/openapi.json get /members Lists the workspace's members and its pending invitations. Invite and remove members in the app. # Install Superlog MCP Source: https://docs.superlog.sh/assistants/claude Connect Claude Code or the Claude apps to the Superlog MCP server and manage your workspace from chat. Connect Claude to Superlog and ask it to create an automation, start a run, check why a run failed, change tag mode, or connect an integration. Claude uses the [Superlog MCP server](/api-reference/mcp) and acts as you in the workspace you choose when you sign in. For Cursor, Codex, VS Code, and other MCP clients, see [Connect a client](/api-reference/mcp#connect-a-client). ## Claude Code **1. Install the plugin** ```bash theme={null} claude plugin marketplace add superloglabs/claude-plugin claude plugin install superlog@superlog ``` The plugin source is [superloglabs/claude-plugin](https://github.com/superloglabs/claude-plugin). **2. Sign in** Start Claude Code and run `/mcp`. Select `plugin:superlog:superlog`, choose **Authenticate**, and sign in to Superlog in your browser. Choose a workspace and approve access. To add the server without the plugin, run: ```bash theme={null} claude mcp add --transport http superlog https://superlog.sh/api/mcp ``` Then run `/mcp` and sign in the same way. ## Claude apps Add Superlog as a custom connector in Claude on the web, desktop, or mobile: 1. Open **Settings → Connectors** and click **Add custom connector**. 2. Enter the name `Superlog` and the URL `https://superlog.sh/api/mcp`. 3. Click **Connect**, sign in to Superlog, choose a workspace, and approve access. On Team and Enterprise plans, an owner adds the connector for the organization first. Members then connect their own Superlog account. ## Connect integrations from chat Ask Claude to connect an integration, such as "Connect GitHub to my Superlog workspace." Claude returns a consent link. Open it in a browser signed in to the same Superlog account and workspace, approve access, and return to the conversation. Claude then checks the connection and continues. Integrations that need an API key or other credential return a secure setup link instead. Enter the credential in Superlog, not in the conversation. ## What stays in the app Claude cannot read or add workspace secret values or model API keys, so those values never pass through the model. Members, billing, and new API keys are also managed in the Superlog app. To switch workspaces, sign out of the connector and sign in again. In Claude Code, choose **Clear authentication** in `/mcp`. # Connectors Source: https://docs.superlog.sh/automations/connectors Give an automation's agent access to GitHub, Slack, Sentry, Datadog, Linear, custom MCP servers, and workspace secrets. Connectors are the tools an automation's agent can use during a run. Add them under **Connectors** in the automation editor with **Add connector**. > [!WARNING] > > Runs use selected connectors directly. Write actions, such as opening a pull request, posting to Slack, or creating a Linear issue, run without human approval. Add only the connectors the task needs. ## Available connectors | Connector | What the agent can read | What the agent can do | | - | - | - | | **GitHub** | Pull requests, commits, comparisons, issues, and files in your repositories. It can also fetch other branches, tags, and pull requests. | Open a pull request with its changes. | | **Slack** | Channels and threads it has access to. It can search for channels. | Post messages and thread replies. Add and remove reactions. | | **Sentry** | Issues, events, traces, and projects through Sentry's MCP server. | — | | **Datadog** | Logs, metrics, monitors, and traces through Datadog's MCP server. | Any tool the Datadog MCP server exposes. | | **Linear** | Teams, projects, and issues through Linear's read-only MCP server. | Create issues, with assignee, labels, priority, project, state, and parent. | | **Custom MCP** | Every tool your server exposes. | Every tool your server exposes. | | **Workspace secrets** | — | Call your own APIs with a secret the agent never sees. See [Workspace secrets](/settings/workspace-secrets). | If a tool is not connected yet, the picker shows **Connect** next to it. Click **Manage** on a connector to change its connection in settings. A connection that is already used as a trigger shows **Trigger** in the picker. A Slack trigger without a Slack connector lets the agent read and reply only in the thread that started the run. ## GitHub Repositories are configured in their own **Repositories** section and are required. They are checked out into the sandbox without git history. The sandbox has no GitHub credentials. Superlog fetches code and opens pull requests on the agent's behalf. When the agent opens a pull request, Superlog creates a new branch from the agent's changes and opens the pull request against the branch that was checked out. The run page shows a card with **View pull request**. ## Slack The agent can post up to 40,000 characters per message, and can reply in threads. The run page notes each message it sends. ## Linear The agent can read Linear and create issues. Each created issue appears on the run page with **View issue**. ## Custom MCP servers Add one from the picker with **Add custom MCP server**, or from **Integrations**. Superlog passes every tool the server exposes to the agent without filtering. Expose only the tools you want the agent to use. See [Custom MCP servers](/integrations/custom-mcp). ## Workspace secrets Pick up to 20 secrets under **Workspace secrets** in the connector picker. Each secret is available in the sandbox as an environment variable named after the secret. The variable holds a placeholder. Superlog replaces it with the real value only on requests to the secret's allowed hosts. ## Other integrations AWS, Google Cloud, PostHog, Grafana, Axiom, Dash0, ClickStack, Langfuse, Upstash, Supabase, and Vercel are available in [Tag mode](/tag-mode). To use another tool from an automation, connect it as a [custom MCP server](/integrations/custom-mcp) or call its API with a [workspace secret](/settings/workspace-secrets). # Models and harnesses Source: https://docs.superlog.sh/automations/models Choose any model and agent harness for each automation, and run on your own API keys or ChatGPT subscription. Each automation picks its own model and harness. You can switch providers without rebuilding your automations, and you can run on your own API keys or your ChatGPT subscription instead of the usage included in your plan. ## Choose a model In the automation editor, click **Choose model** in the **Agent instructions** toolbar. Pick a provider, then a model from its list. | Provider | Harnesses | | - | - | | OpenAI | Codex, OpenCode | | Anthropic | Claude Agent SDK, OpenCode | | Google Gemini | OpenCode | | xAI | OpenCode | | Mistral | OpenCode | | DeepSeek | OpenCode | Model lists are loaded from each provider's current catalog. The provider decides at run time whether a model is available to your key. ## Choose a harness The harness is the agent program that runs the model in the sandbox. When you pick a model, Superlog switches to a compatible harness: Codex for OpenAI, the Claude Agent SDK (shown as **Anthropic**) for Anthropic, and OpenCode for the others. Click **Harness** to change it. | Harness | Providers | | - | - | | **Codex** | OpenAI. Required to use a ChatGPT subscription. | | **Anthropic** (Claude Agent SDK) | Anthropic | | **OpenCode** | All six providers | All harnesses run unattended, without approval prompts. ## Where inference comes from Superlog picks the inference source when each run starts: 1. **ChatGPT subscription**, if one is connected and the automation uses the Codex harness. 2. **Your API key** for the model's provider. With several keys for one provider, the newest is used. 3. **Included usage** from your plan, if neither of the above applies. If the provider rejects your key, or your key cannot use the selected model, the run fails with a message that names the problem. It does not fall back to included usage. ## Add an API key **1. Open model settings** Go to **Settings → Models**. **2. Add the key** Under **Add an API key**, choose the provider, enter a label, and paste the key. Click **Add key**. **3. Check the result** Superlog checks the key against the provider's model list before saving it. The key appears under **API keys** with its label, provider, last four characters, and status. From then on, every automation that uses that provider runs on your key, and your provider bills the model usage. Keys are encrypted and never enter the automation sandbox. Click **Replace** to rotate a key, or **Remove** to delete it. A key that an automation is using cannot be removed. ## Connect a ChatGPT subscription Automations that use the Codex harness can run on a ChatGPT plan. The subscription takes priority over any OpenAI API key, and usage counts against that plan's Codex limits. **1. Start the sign-in** Go to **Settings → Models**, click **Connect ChatGPT**, then **Connect subscription**. **2. Enter the code** Superlog shows a one-time code. Click **Continue to ChatGPT**, sign in, and enter the code. If ChatGPT asks, enable device-code login in your ChatGPT security settings. **3. Finish** When the sign-in completes, the subscription appears with **Codex harness only**. Every automation in the workspace can use it. If the subscription stops working, it shows **Reconnect**. Sign in again to restore it. > [!NOTE] > > Superlog uses OpenAI's official Codex client for sign-in and inference. Your tokens are encrypted, and each run's sandbox holds only placeholders that are replaced at the network boundary. Anthropic subscription sign-in is not available. # Automations Source: https://docs.superlog.sh/automations/overview What automations can do: start from your tools, work in your code with a coding agent, and report back where your team works. An automation hands a task to a coding agent. Each time one of its triggers fires, Superlog starts a fresh sandbox, checks out your repositories, and runs the agent on the task. ## What starts a run | Source | Events | | - | - | | Slack | A new message in a channel, an app mention, or both | | Sentry | A new issue or a regression | | Superlog errors | A new error or a regression, in workspaces with [telemetry](/telemetry/errors) | | Axiom, SigNoz, Honeycomb | A monitor or alert fires | | Better Stack | An incident starts | | DevRev | A new ticket | | GitHub | A pull request is opened or merged | | Discord | The automation command in a channel | | Schedule | Every hour, day, or week, or a custom cron | | Webhook | An HTTP request from any system | You can also start a run by hand with **Run now**, or try one out with **Test**. An automation can have up to 10 triggers. See [Triggers](/automations/triggers). ## What the agent can do * **Read and change your code.** Up to 10 GitHub repositories are checked out in the sandbox. The agent can run commands, tests, and builds there. * **Use your tools.** [Connectors](/automations/connectors) give the agent Slack, Sentry, Datadog, Linear, custom MCP servers, and workspace secrets. * **Follow your playbooks.** [Skills](/automations/skills) add reusable instructions and scripts to a run. * **Open pull requests.** Pull requests from runs are listed under [PRs](/automations/pull-requests). Review comments on them continue the run that opened them. * **Report back.** The agent replies in the Slack or Discord thread that started the run. It can also post to Slack channels and create Linear issues. Other runs can send results to Slack [notification](/automations/runs#notifications) channels. * **Take follow-ups.** Reply in the run, or in its Slack thread, and the agent continues in the same sandbox with the same context. See [Runs](/automations/runs). ## What teams automate | Area | Examples | | - | - | | Support | Answer support and community questions from the code and docs. Match reports to known errors. | | Bug triage | Investigate alerts from Sentry, Datadog, Grafana, Axiom, SigNoz, Honeycomb, and Better Stack. Fix bugs reported in Slack. Fix regressions. | | Scheduled reviews | Reliability checks, and reviews of observability, performance, architecture, and test coverage. | Each of these is a template. See [Templates](/automations/templates). ## Models Every automation picks its model and agent harness: Codex, Claude Agent SDK, or OpenCode. Runs can use your own API keys, your ChatGPT subscription, or the usage included in your plan. See [Models and harnesses](/automations/models). ## Limits | Setting | Limit | | - | - | | Instructions | 50,000 characters | | Triggers | 1 to 10 | | Repositories | 1 to 10 | | Slack or Discord channels per trigger | 50 | | Sentry projects per trigger | 100 | | Notification channels | 10 | | Run time | 30 minutes | # Pull requests Source: https://docs.superlog.sh/automations/pull-requests See every pull request your automations opened, review it in Superlog, and have the agent address GitHub reviews. When an automation run opens a pull request, Superlog records it. The **PRs** page in the sidebar lists them for the whole workspace, newest first. Pull requests need [GitHub](/integrations/github) to be connected. ## The pull requests list Each row shows: | Column | What it shows | | - | - | | **Pull request** | The title, with the repository and number, such as `acme/api #42`. | | **Automation** | The automation that opened it. Click it to open the run. | | **Status** | The current state on GitHub. | | **Opened** | When the run opened it. | The list shows 25 pull requests per page. Use **Previous** and **Next** to move between pages. ## Statuses Superlog reads each pull request's state from GitHub when you open the page. | Status | Meaning | | - | - | | **Open** | Open and ready for review. | | **Draft** | Open as a draft. | | **Merged** | Merged into its base branch. | | **Closed** | Closed without merging. | | **Unknown** | Superlog could not read the pull request from GitHub. | ## Review a pull request Click a row to open the pull request. The header shows its title, status, the automation that opened it with a link to the run, the head and base branches, and the lines and files changed. Click **View on GitHub** to open it on GitHub. The page has two tabs: * **Overview** shows the **Description**, the **Comments** and reviews, and the **Commits**. When there are more comments than fit, a link takes you to GitHub for the rest. * **Files changed** shows the diff. Switch between **Unified** and **Split** layouts. If Superlog no longer has access to the repository, the page says so. Reconnect GitHub or grant the GitHub App access to the repository again. See [GitHub](/integrations/github). ## From the run Pull requests also appear as cards in the run's transcript. See [Runs](/automations/runs). From the run page, you can send a follow-up asking the agent to change its pull request. The agent can push commits only to pull requests its own run opened. ## Follow-ups from GitHub reviews When someone submits a review on a pull request that a run opened, the review continues that run. The agent does not start over in a new run. **1. Submit a review on GitHub** Leave inline comments, a review summary, or both, and submit the review. **2. The run picks it up** Superlog sends the review and its inline comments to the run as a new message, shown as from the reviewer on GitHub. The agent checks out the pull request's latest commit. **3. The agent addresses the comments** The agent checks each comment against the code and fixes the ones that are right. It pushes the fixes as one commit to the same pull request. It then replies to each comment with what changed or why no change is needed, and resolves it. The agent treats review text as claims to check, not as instructions. The run page shows "Pushed a commit to pull request #N." when it pushes. ### Which reviews start a follow-up * The review must be submitted, with a summary or at least one inline comment. * The reviewer must be an owner, member, or collaborator of the repository. Reviews from other people are ignored, so outside users of a public repository cannot steer the agent. * Review bots, such as automated code reviewers, are accepted. Each pull request accepts follow-ups from up to 5 bot reviews. Reviews from people are not limited. * The automation must be active. Reviews on pull requests from a paused automation are ignored. If the run is still working when a review arrives, the agent answers it in the next turn. # Runs Source: https://docs.superlog.sh/automations/runs Follow an automation run live, send follow-ups, stop runs, and post results to Slack. A run is one execution of an automation. Each run has its own sandbox, transcript, and result. ## Run history Open an automation to see its **Run history** tab. Each row shows the run's title and source (Slack, Sentry, Discord, Schedule, or Manual), when it started, how long it took, and its result. The result is the pull request it opened, the first line of the agent's final message, or the failure reason. | Status | Meaning | | - | - | | **Queued** | Waiting for a worker. | | **Running** | The agent is working in its sandbox. | | **Completed** | The agent finished. | | **Failed** | The run stopped with an error, such as hitting its time limit or the usage allowance. | | **Cancelled** | Someone stopped the run. | ## Follow a run Click a run to open it. The page shows the trigger event with a link back to the source, followed by the agent's messages as it works. Tool calls are grouped, for example "Ran 4 tools" with a summary of the files read, commands run, and services queried. Expand a group to see each call. Pull requests, Linear issues, and Slack messages the agent creates appear as cards in the transcript. ## Send a follow-up When a run finishes, type in the box at the bottom of the run page to continue it. The agent picks up in the same sandbox with the same files and context. This works for completed, failed, and cancelled runs. The automation must be active. For Slack-triggered runs, replying in the Slack thread does the same thing. The sandbox is kept for 24 hours after the last turn so follow-ups can resume it. Runs on a ChatGPT subscription start a new sandbox for each turn. ## Stop a run Click **Stop** on the run page, or the **×** next to an active run in the run history. ## Slack progress card When a Slack message starts a run, Superlog posts a card in that thread. The card shows the agent's latest steps while it works, then **Automation complete** or **Automation stopped**, with a **View run** link. ## Notifications Scheduled automations can post each finished run to Slack. **1. Add a notification** In the automation's settings, under **Notifications**, click **Add notification**, then **Post to Slack**. **2. Pick channels** Choose up to 10 channels. The agent can post to these channels during the run. Channels it did not post to receive its final message with a **View run** link. If the run fails, every channel gets the failure message. Notifications are available for automations with a schedule, Sentry, errors, Axiom, SigNoz, Honeycomb, Better Stack, GitHub, or webhook trigger. Slack and Discord runs reply where their event came from instead. ## Sandboxes and limits Each run gets a fresh sandbox with your repositories checked out. The agent is told it is running unattended and that the trigger event is untrusted input. A run can last up to 30 minutes. When your usage allowance is used up, a turn that has already started finishes, and new runs fail with a usage-limit message until the allowance resets or you upgrade. See [Billing](/settings/billing). # Skills Source: https://docs.superlog.sh/automations/skills Give automations reusable instructions, reference files such as an OpenAPI spec, and the secrets to call an API. A skill is a folder of instructions and reference files that an agent reads before a task the skill covers. A skill can also carry workspace secrets, so the agent can call the API it describes. Skills belong to the workspace, and any automation can use them. Skills follow the Agent Skills format. A skill folder written for Claude Code or Codex, with a `SKILL.md` and its files, can be uploaded as is. ## The skills list Open **Skills** in the sidebar. Each row shows the skill's name and description, its file count, its secrets, how many automations use it (**Used by**), and when it was last updated. Click a row to edit the skill. ## Create a skill **1. Start a skill** On the **Skills** page, click **Create skill**. **2. Fill in the details** Under **Details**, enter a **Name** and a **Description**. The name uses lowercase letters, numbers, and single hyphens, such as `billing-api`. The description tells the agent when to use the skill. **3. Write the instructions** Under **Instructions**, explain how to do the task: for an API, the base URL, how to authenticate, the endpoints that matter, and examples. **4. Add reference files** Under **Reference files**, click **Add files, such as an OpenAPI spec**. Files keep their names inside the skill folder. **5. Add secrets** Under **Secrets**, click **Add secret** and pick a workspace secret, or choose **Create a secret** to store a new one. See [Workspace secrets](/settings/workspace-secrets). **6. Save** Click **Save**. To import an existing skill, click **Upload folder** and choose a folder that contains a `SKILL.md`. Superlog reads the name and description from its front matter and the rest as instructions. The folder's other text files become reference files. Hidden files are left out. Binary files and unsupported file names are skipped, and the editor lists what it skipped. > [!WARNING] > > Skill text is stored as written, and the agent can read it. If the instructions or a file look like they contain a credential, the editor warns you. Store keys as workspace secrets instead. ## Use a skill in an automation **1. Open the connector picker** In the automation editor, under **Connectors**, click **Add connector**. **2. Pick the skill** Choose the skill under **Skills**. To make a new one, choose **Create a skill**. It opens in a new tab, and the picker lists it when you return. Selected skills appear under **Connectors**. Click **Manage** to open a skill, or the trash icon to remove it from the automation. An automation can use up to 20 skills. ## How runs use skills At the start of each turn, Superlog writes every skill the automation uses into the sandbox at `.responder/skills//`. The folder holds the `SKILL.md` and the reference files. The agent gets a list of the skills with their descriptions and is told to read a skill's `SKILL.md` before a task it covers. A skill's secrets are added to the run's environment variables, next to the automation's own secrets. As with any workspace secret, the variable holds a placeholder, and Superlog swaps in the real value only on requests to the secret's allowed hosts. Skills are read fresh on every turn. When you edit a skill, the next run or follow-up of every automation that uses it gets the new version. Agents also find skills in your repositories. Superlog lists `SKILL.md` files under `.agents/skills/` and `.claude/skills/`, and `AGENTS.md` and `CLAUDE.md` files, from the checked-out repositories, whatever the harness. ## Delete a skill Open the skill and click **Delete**. You cannot delete a skill that an automation still uses. Remove it from those automations first. The **Used by** section on the skill page lists them, with an **Open** link to each one. ## Limits | Setting | Limit | | - | - | | Name | 64 characters, unique in the workspace | | Description | 1,024 characters | | Instructions | 100,000 characters | | Reference files | 100 files, 3 MB in total, text only | | Secrets per skill | 20 | | Skills per automation | 20 | # Templates and sharing Source: https://docs.superlog.sh/automations/templates Start an automation from a built-in template for bug triage, support, or scans, and share your own automations as templates. Templates fill in an automation's triggers, instructions, and connectors. You choose the channels, projects, and repositories, then save. Templates are based on workflows used by fast-moving engineering teams. ## Use a template **1. Open the gallery** Open **Automations**. The gallery is under **Start from a template**. Filter by **Suggested**, **All**, **Support**, **Bug triage**, or **Scans**. **2. Pick a template** Click a card. The editor opens with the template applied. Superlog uses the first existing connection for each trigger and connector. **3. Finish the setup** Connect any tools that are not connected yet, choose the channels or projects for each trigger, add a repository, and choose a model. Click **Start blank** to drop the template. **4. Review and save** Read the instructions and adjust them for your team, for example the Slack channel to post in. Then click **Save**. Scheduled templates default to 09:00 in your browser's time zone. Weekly templates run on Mondays. ## Built-in templates ### Support | Template | Trigger | Connectors | What the agent does | | - | - | - | - | | **Answer support questions** | Slack: new message in channel | GitHub | Finds the answer in the repositories, docs, and code. Replies in the thread with a short answer and links. Says if it is a bug. Does not guess. | | **Answer community questions** | Discord: `/automate` command | GitHub | Answers outside users in a friendly way and links to public docs. Never shares private paths, credentials, or plans. | | **Match reports to known errors** | Slack: app mentioned | Sentry, GitHub | Finds the matching Sentry issue and replies with the issue, affected users, and status. Suggests a workaround from the code. If nothing matches, lists the details needed to reproduce. | ### Bug triage | Template | Trigger | Connectors | What the agent does | | - | - | - | - | | **Alert on critical Sentry issues** | Sentry: new issue | GitHub, Slack | Rates severity, traces the cause to the suspected commit and owner, and posts a summary to Slack. Opens a pull request with a regression test when the fix is small. | | **Fix bugs reported in Slack** | Slack: new message in channel | GitHub | Reproduces the bug with a failing test, fixes it, opens a pull request, and replies with the link. If it cannot reproduce the bug, says what it tried. | | **Fix regressions** | Sentry: issue regression | GitHub, Datadog | Finds the earlier fix and the change that undid it, checks Datadog logs, and opens a pull request that restores the fix with a regression test. | ### Scans | Template | Trigger | Connectors | What the agent does | | - | - | - | - | | **Reliability check** | Every hour | GitHub, Sentry, Datadog, Slack | Compares the past hour with the same hour over the last 7 days in Sentry and Datadog. Posts to Slack only when something is out of range. | | **Review observability** | Every week | GitHub, Sentry, Datadog | Finds code paths behind the past week's errors that have poor telemetry. Opens a pull request that adds logs, tags, and spans, without secrets or personal data. | | **Review performance** | Every week | GitHub, Datadog, Slack | Finds the slowest endpoints, jobs, and queries. Opens pull requests for safe fixes and posts a report to Slack. | | **Review architecture** | Every week | GitHub, Slack | Reviews the past 7 days of merges for layering problems, wrong-way dependencies, and duplicated logic. Posts findings to Slack. | | **Review test coverage** | Every week | GitHub, Sentry | Finds recent code and recent Sentry errors without tests and opens a pull request that adds them. | ## Share an automation as a template You can share any automation as a link. Anyone with the link can see it and set up a copy in their own workspace. **1. Create the link** Open the automation and click **Share**, then **Create link**. Click **Copy link**. **2. Update or stop sharing** Later edits are not shared until you click **Update shared copy**. Click **Stop sharing** to disable the link. The shared page shows the automation's name, description, instructions, trigger types, connectors, and your workspace name. Channels, projects, repositories, connections, secrets, and model settings stay private. Schedules run in the recipient's time zone. When someone opens the link, they click **Use this automation**. Superlog opens a new automation with the shared setup. They connect their own tools, pick their own channels and repositories, and choose a model. Visitors without an account can sign up first and return to the setup. # Triggers Source: https://docs.superlog.sh/automations/triggers Start automation runs from Slack messages and mentions, Sentry issues, Discord commands, or a schedule. A trigger decides when an automation runs. Each automation has 1 to 10 triggers, and any of them starts a run. You can also start a run by hand with **Run now** or **Test**. ## Add a trigger In the automation editor, click **Add trigger** and pick an event. If the tool is not connected, the trigger card shows **Connect**. Approve access in the pop-up window and return to the editor. Your draft stays open. If your workspace has more than one connection for the tool, choose one under **Choose a workspace**. Then pick the channels or projects to watch. Use **Refresh channels** or **Refresh projects** if a new one is missing. ## Slack | Event | Starts a run when | | - | - | | **New message in channel** | Someone posts a new message in a selected channel. | | **App mentioned** | Someone mentions the Superlog app in a selected channel. | | **Message posted or app mentioned** | Either of the above. | Pick up to 50 channels. To watch a private channel, invite the Superlog app to it first. Superlog ignores messages from its own app. Alerts that other tools post to Slack, such as Datadog, PostHog, Sentry, or CloudWatch notifications, start runs. Recovery and resolved notifications from those tools are ignored. While a run is active, Superlog posts a live progress card in the thread that started it. When someone replies in that thread, the reply continues the same run instead of starting a new one. ## Sentry | Event | Starts a run when | | - | - | | **New issue** | Sentry creates a new issue in a selected project. | | **Issue regression** | A resolved issue comes back. | | **New issue or regression** | Either of the above. | Pick up to 100 projects. The run is titled with the Sentry short ID and issue title, and the agent receives the issue details. ## Errors This trigger is available in workspaces with telemetry, which is in early access. It starts runs from Superlog's own [error issues](/telemetry/errors). | Event | Starts a run when | | - | - | | **New error** | Superlog groups an exception into a new issue. | | **Error regression** | A resolved issue comes back. | | **New error or regression** | Either of the above. | You can limit the trigger to some services. The agent receives the issue with its newest stack trace, trace ID, and attributes. ## Discord | Event | Starts a run when | | - | - | | **Automation command in channel** | Someone runs `/automate` in a selected channel. | The command takes an optional `context` option. Its text is passed to the agent with the trigger: ```text theme={null} /automate context: Check whether last night's payment latency spike came back ``` `/automate` starts every active automation that watches the channel. Discord replies only to the person who ran the command, with **Automation started.** or a message saying that no automation is configured for the channel. Results are not posted back to Discord. Add a Slack connector or a GitHub repository so the agent can report somewhere. ## Schedule | Frequency | Options | | - | - | | **Every hour** | Runs at the top of each hour. | | **Every day** | Pick the time, on the hour. | | **Every week** | Pick the day and the time. | Schedules use the time zone shown on the trigger card, which defaults to your browser's. If a scheduled run is missed by less than an hour, it still runs. Older missed runs are skipped. Scheduled automations can post each finished run to Slack. See [Notifications](/automations/runs#notifications). ## Manual runs **Run now** starts a run with no trigger event. **Test** opens a chat where your message is treated as the trigger event. Both need the automation to be active. # AWS CloudWatch Source: https://docs.superlog.sh/collect-telemetry/aws Stream CloudWatch metrics and logs to Superlog through Amazon Data Firehose with a CloudFormation stack. > [!NOTE] > > Telemetry is in early access. To turn it on for your workspace, [book a call](https://cal.com/superlog/yc) or ask in [Discord](https://discord.gg/wJ56aRh8hx). A CloudFormation stack in your account streams one region's CloudWatch metrics and CloudWatch Logs to Superlog through Amazon Data Firehose. Metric Streams, Firehose, and log delivery are billed to your AWS account. Deploy one stack per region. **1. Open the AWS setup** Open **Overview** in the sidebar, click **Add telemetry**, and pick **Amazon Web Services**. **2. Choose a region** Pick the **Region** and click **Create stack link**. Superlog creates an ingest key for the stack. **3. Deploy the stack** Click **Open in the AWS console** to create the stack with its parameters filled in. Or download the template and run the `aws cloudformation deploy` command shown on the page. The link and command contain the new ingest key. Copy them now. They are not shown again. The stack: * Streams metrics from these namespaces: `AWS/EC2`, `AWS/EBS`, `AWS/RDS`, `AWS/ApplicationELB`, `AWS/NetworkELB`, `AWS/ELB`, `AWS/Lambda`, `AWS/ECS`, `ECS/ContainerInsights`, `AWS/DynamoDB`, `AWS/SQS`, `AWS/SNS`, `AWS/S3`, `AWS/ElastiCache`, `AWS/ApiGateway`, and `AWS/CloudFront`. * Forwards every CloudWatch Logs log group in the region with an account-level subscription filter. * Keeps records Firehose could not deliver in an S3 bucket for a week. Stack parameters control the volume. Set `EnableMetrics` or `EnableLogs` to `false` to skip a signal. Set `LogsFilterPattern` to a CloudWatch Logs filter pattern to forward only matching events. To stop streaming, delete the stack in CloudFormation. **Remove** in Superlog revokes the stack's key. # Google Cloud Source: https://docs.superlog.sh/collect-telemetry/google-cloud Have Superlog read Cloud Logging and Cloud Monitoring from a connected Google Cloud project. > [!NOTE] > > Telemetry is in early access. To turn it on for your workspace, [book a call](https://cal.com/superlog/yc) or ask in [Discord](https://discord.gg/wJ56aRh8hx). Superlog reads a project's Cloud Logging entries every minute and its Cloud Run, Compute Engine, Cloud SQL, load balancer, and Pub/Sub metrics every five minutes. Data Access audit logs are skipped. [Connect the project](/integrations/cloud#google-cloud) in **Integrations** first. Then open **Overview** in the sidebar, click **Add telemetry**, pick **Google Cloud**, choose the project, and click **Start reading**. # Send from an OpenTelemetry Collector Source: https://docs.superlog.sh/collect-telemetry/opentelemetry-collector Add Superlog as an OTLP/HTTP exporter to a Collector you already run. > [!NOTE] > > Telemetry is in early access. To turn it on for your workspace, [book a call](https://cal.com/superlog/yc) or ask in [Discord](https://discord.gg/wJ56aRh8hx). You need an ingest key. See [Create an ingest key](/guides/instrument-your-app#create-an-ingest-key). If you already run a Collector, add an `otlphttp` exporter and use it in each pipeline: ```yaml theme={null} exporters: otlphttp/superlog: endpoint: https://superlog.sh/api/ingest headers: x-api-key: ${env:SUPERLOG_INGEST_KEY} service: pipelines: traces: receivers: [otlp] processors: [batch] exporters: [otlphttp/superlog] metrics: receivers: [otlp] processors: [batch] exporters: [otlphttp/superlog] logs: receivers: [otlp] processors: [batch] exporters: [otlphttp/superlog] ``` The `otlphttp` exporter adds `/v1/traces`, `/v1/metrics`, and `/v1/logs` to the endpoint. Gzip compression, its default, is supported. Use `otlphttp`, not the gRPC `otlp` exporter: Superlog accepts OTLP over HTTP only. Use `https://us.superlog.sh/api/ingest` for a workspace in the US region. # Collect telemetry Source: https://docs.superlog.sh/collect-telemetry/overview Every way to send logs, traces, and metrics to Superlog: OpenTelemetry SDKs, the browser SDK, a Collector, Vercel, AWS, and Google Cloud. > [!NOTE] > > Telemetry is in early access. To turn it on for your workspace, [book a call](https://cal.com/superlog/yc) or ask in [Discord](https://discord.gg/wJ56aRh8hx). Superlog stores logs, traces, and metrics as OpenTelemetry. Send them from your code, from a Collector you already run, or straight from your cloud provider. ## Choose a source | Source | Sends | Setup | | - | - | - | | [OpenTelemetry SDKs](/guides/instrument-your-app) | Logs, traces, metrics | Ingest key and three environment variables. Node.js, Python, Go, Java, and any other OpenTelemetry SDK. | | [Browser and React](/guides/browser) | Errors, traces, page loads, Web Vitals | `@superlog/browser` with an ingest key. | | [OpenTelemetry Collector](/collect-telemetry/opentelemetry-collector) | Logs, traces, metrics | Add an `otlphttp` exporter. | | [Vercel](/collect-telemetry/vercel) | Traces, logs | Connect Vercel. Superlog creates the drains. | | [AWS CloudWatch](/collect-telemetry/aws) | Metrics, logs | Deploy a CloudFormation stack per region. | | [Google Cloud](/collect-telemetry/google-cloud) | Logs, metrics | Connect a project. Superlog reads from it. | Moving from another vendor? See the migration guides for [Datadog](/guides/migrate/datadog), [New Relic](/guides/migrate/new-relic), and [Dynatrace](/guides/migrate/dynatrace). ## Ingest endpoint Code and Collectors send OTLP over HTTP to your region's endpoint: | Region | Endpoint | | - | - | | EU | `https://superlog.sh/api/ingest` | | US | `https://us.superlog.sh/api/ingest` | * Send to `/v1/logs`, `/v1/traces`, or `/v1/metrics` under the endpoint. OpenTelemetry SDKs and the Collector add these paths for you. * Send the ingest key as `x-api-key: ` or `Authorization: Bearer `. * Use `http/protobuf` or `http/json`. Gzip is supported. gRPC is not. * A request can be up to 8 MB. ## Ingest keys An ingest key decides which workspace the data goes to. Keys start with `sl_ingest_`. Create one from **Overview** in the sidebar. See [Create an ingest key](/guides/instrument-your-app#create-an-ingest-key). **Settings → Ingest keys** lists each key and when it last sent data. Revoke a key there to stop it. Vercel and AWS sources create their own keys, and removing the source revokes its key. ## Name your services Set these resource attributes on every service. Superlog groups and filters your data by them. | Attribute | Example | | - | - | | `service.name` | `checkout-api` | | `deployment.environment.name` | `production` | | `service.version` | `1.4.2` | With an OpenTelemetry SDK, set them with `OTEL_SERVICE_NAME` and `OTEL_RESOURCE_ATTRIBUTES`. # Vercel Source: https://docs.superlog.sh/collect-telemetry/vercel Send traces and logs from your Vercel deployments with drains Superlog creates for you. > [!NOTE] > > Telemetry is in early access. To turn it on for your workspace, [book a call](https://cal.com/superlog/yc) or ask in [Discord](https://discord.gg/wJ56aRh8hx). Superlog creates a trace drain and a log drain on your Vercel team. Traces arrive as OpenTelemetry. Logs carry their request and trace IDs. Drains need a Pro or Enterprise team. **1. Open the Vercel setup** Open **Overview** in the sidebar, click **Add telemetry**, and pick **Vercel**. **2. Connect Vercel** Click **Connect Vercel** and install the Superlog integration on your team. The drains cover the projects you share with the integration. **3. Create the drains** Click **Create drains**. Superlog creates an ingest key for the drains. The source appears under **Connected** with its status and when data last arrived. **Remove** deletes the drains and revokes their key. If Vercel refuses, check that the team is on Pro or Enterprise and that the integration has the Drains permission. Reconnect Vercel to grant it. # Terraform provider Source: https://docs.superlog.sh/developer/terraform Manage Superlog alerts, dashboards, and synthetic checks with Terraform or OpenTofu, and export the ones you already have. The Superlog provider manages alerts, dashboards, and synthetic checks as code. It works with Terraform and OpenTofu. | | | | - | - | | Source address | `superloglabs/superlog` | | Latest version | `0.1.0` | | Registry | [registry.terraform.io/providers/superloglabs/superlog](https://registry.terraform.io/providers/superloglabs/superlog/latest) | | Source code | [github.com/superloglabs/terraform-provider-superlog](https://github.com/superloglabs/terraform-provider-superlog) | ## Configure the provider ```hcl theme={null} terraform { required_providers { superlog = { source = "superloglabs/superlog" version = "~> 0.1" } } } provider "superlog" { # https://superlog.sh for the EU region, https://us.superlog.sh for the US region. endpoint = "https://superlog.sh" } ``` | Argument | Environment variable | Description | | - | - | - | | `api_key` | `SUPERLOG_API_KEY` | A Superlog API key. Sensitive. | | `endpoint` | `SUPERLOG_ENDPOINT` | Your region's address. Defaults to `https://superlog.sh`. | Create the key under **Settings → API keys**. See [API keys](/settings/api-keys). The provider acts as the member who created the key, in that key's workspace. Set `endpoint` to the region your workspace is in: `https://superlog.sh` for EU or `https://us.superlog.sh` for US. ```bash theme={null} export SUPERLOG_API_KEY=slk_... terraform init ``` ## Resources and data sources | Name | Type | What it manages | | - | - | - | | `superlog_alert` | Resource | Threshold alerts on logs, spans, or a metric. See [Alerts](/telemetry/alerts). | | `superlog_dashboard` | Resource | Dashboards, their variables, and all of their widgets. See [Dashboards](/telemetry/dashboards). | | `superlog_synthetic_check` | Resource | Scheduled HTTP checks. See [Synthetic checks](/telemetry/synthetics). | | `superlog_slack_channel` | Data source | Looks up a Slack channel by name for an alert or check to post to. | Two behaviors to know: * `superlog_dashboard` owns all of its widgets. Widgets added in Superlog are removed on the next apply. * `superlog_synthetic_check` stores `secret_headers` encrypted, and Superlog never returns their values. Changes made to them outside Terraform are not detected. Every resource has a read-only `url` that links to the object in Superlog. Import an existing object by the ID from its URL, for example `terraform import superlog_alert.checkout_errors `. ## Example: an alert that posts to Slack This alert fires when checkout logs more than 50 errors in production in 5 minutes, and posts to `#alerts`. Connect [Slack](/integrations/slack) first. The channel must be public, or private with the Superlog app in it. ```hcl theme={null} data "superlog_slack_channel" "alerts" { name = "alerts" } resource "superlog_alert" "checkout_errors" { name = "Checkout errors" source = "logs" aggregation = "count" comparator = "gt" threshold = 50 filter = { service = "checkout" severity = "ERROR" attributes = [ { key = "deployment.environment", value = "production" }, ] } slack = { channel_id = data.superlog_slack_channel.alerts.channel_id integration_account_id = data.superlog_slack_channel.alerts.integration_account_id } } ``` While the value is past the threshold, the alert posts once to the channel and posts the recovery in the same thread. Without `slack`, the alert only records its history in Superlog. If more than one connected Slack workspace has a channel with that name, set `workspace` on the data source to the Slack workspace's name. Alert defaults: `window_minutes` is 5, `evaluation_interval_seconds` is 60, `group_mode` is `single`, and `enabled` is `true`. To check each service separately, set `group_mode = "per_group"` and `group_by = "service.name"`. ## Export existing configuration Superlog can write Terraform for objects you already have. The output has an `import` block for each one, so `terraform apply` adopts the existing objects instead of creating copies. * **One object:** click **Copy as Terraform** on an alert, dashboard, or synthetic check page. * **The whole workspace:** call `GET /terraform` on the [management API](/api-reference/introduction). * **From an agent:** call the `export_terraform` tool on the [MCP server](/api-reference/mcp). ```bash theme={null} curl -s -H "Authorization: Bearer $SUPERLOG_API_KEY" \ https://superlog.sh/api/v1/terraform | jq -r .hcl > superlog.tf terraform init && terraform apply ``` Without parameters, the export includes every alert, dashboard, and synthetic check. To export only some, pass `alertIds`, `dashboardIds`, or `syntheticCheckIds` as comma-separated IDs. Secret header values of synthetic checks become sensitive variables for you to set. # Browser and React Source: https://docs.superlog.sh/guides/browser Send errors, traces, page loads, and Web Vitals from the browser, and upload source maps. > [!NOTE] > > Telemetry is in early access. To turn it on for your workspace, [book a call](https://cal.com/superlog/yc) or ask in [Discord](https://discord.gg/wJ56aRh8hx). The Superlog browser SDK sends errors, sessions, traces, and Web Vitals as standard OpenTelemetry over OTLP/HTTP. It has three packages: * `@superlog/browser`: error capture, breadcrumbs, user and attributes, sessions, `fetch` and `XMLHttpRequest` tracing, navigations, and Web Vitals. * `@superlog/react`: an error boundary, React 19 root error handlers, and route patterns from React Router. * `@superlog/sourcemaps`: a Vite plugin and a CLI that upload your source maps, so errors show and group by the original code. The source is at [github.com/superloglabs/browser](https://github.com/superloglabs/browser). ## Install ```bash theme={null} npm install @superlog/browser @superlog/react ``` ## Create an ingest key The SDK sends to Superlog with an ingest key. Create one for the app. See [Create an ingest key](/guides/instrument-your-app#create-an-ingest-key). The key ships in your page's JavaScript, so anyone who loads the page can read it. An ingest key can only add telemetry to your workspace. It can't read data or change settings. Use a separate key for each app, so you can revoke one without affecting the others. ## Start the SDK Call `init` before the app renders. The SDK sends to `https://superlog.sh/api/ingest` by default. For a workspace in the US region, set `endpoint` to `https://us.superlog.sh/api/ingest`. The SDK adds `/v1/logs` and `/v1/traces` to it. ```ts theme={null} import { init, setUser } from "@superlog/browser"; init({ service: "storefront", ingestKey: import.meta.env.VITE_SUPERLOG_INGEST_KEY, // For a US workspace: endpoint: "https://us.superlog.sh/api/ingest", release: import.meta.env.VITE_RELEASE, environment: import.meta.env.MODE, // Cross-origin APIs that should continue the trace. Same-origin requests always do. tracePropagationTargets: ["https://api.example.com"], }); setUser({ id: user.id, email: user.email }); ``` * `service` is sent as `service.name`, `release` as `service.version`, and `environment` as `deployment.environment.name`. * `ignoreUrls` keeps requests, such as analytics, out of traces and breadcrumbs. * `tracesSampleRate` keeps a share of traces, from 0 to 1. Errors are always sent. * `beforeSend` can change or drop any error, and `beforeBreadcrumb` any breadcrumb. ## React Add the error handlers to your root and instrument the router so errors carry the route pattern: ```tsx theme={null} import { ErrorBoundary, reactErrorHandler } from "@superlog/react"; import { instrumentRouter } from "@superlog/react/router"; import { createBrowserRouter, RouterProvider } from "react-router"; const router = createBrowserRouter(routes); instrumentRouter(router); createRoot(document.getElementById("root")!, { onCaughtError: reactErrorHandler(), onRecoverableError: reactErrorHandler(), }).render( }> , ); ``` With declarative routes, use `SuperlogRoutes` in place of ``: ```tsx theme={null} import { SuperlogRoutes } from "@superlog/react/router"; } /> ``` `@superlog/react` needs React 18 or later, and React Router 6.4 or later for the router integration. ## Capture errors yourself ```ts theme={null} import { addBreadcrumb, captureException, captureMessage, setAttributes } from "@superlog/browser"; try { await pay(cart); } catch (error) { captureException(error, { attributes: { "payment.provider": "stripe" } }); } addBreadcrumb({ category: "checkout", message: "payment started" }); setAttributes({ "app.plan": "pro" }); captureMessage("checkout took longer than 5s", "warning"); ``` ## Upload source maps Source maps let Superlog map minified stack frames back to the original file, line, and function before it groups errors. Uploads use a workspace API key from [Settings → API keys](/settings/api-keys), not the ingest key. With Vite, add the plugin: ```ts vite.config.ts theme={null} import { superlogSourceMaps } from "@superlog/sourcemaps/vite"; export default defineConfig({ plugins: [superlogSourceMaps({ release: process.env.RELEASE })], }); ``` The plugin builds hidden source maps, writes a debug ID into each file and its map, uploads the maps with `SUPERLOG_API_KEY`, and deletes them from the output. A failed upload is printed and the build still succeeds. Set `failOnError: true` to fail the build instead. For other bundlers, run the CLI on the build output: ```bash theme={null} SUPERLOG_API_KEY=... npx superlog-sourcemaps upload dist --release "$RELEASE" --delete ``` Uploads go to `https://superlog.sh`. For a workspace in the US region, pass `url: "https://us.superlog.sh"` to the plugin, or `--url https://us.superlog.sh` to the CLI. ## What gets captured Each error is an OpenTelemetry log record at ERROR severity, so it appears in [Errors](/telemetry/errors) and [Logs](/telemetry/logs). It carries: | Attribute | Value | | - | - | | `exception.type`, `exception.message`, `exception.stacktrace` | The error. Causes follow the stack as `Caused by:` | | `exception.mechanism` | `onerror`, `onunhandledrejection`, `react`, or `manual` | | `exception.handled` | Whether the app caught it | | `app.breadcrumbs` | The last clicks, navigations, console messages, and requests | | `app.debug_ids` | The debug ID of each file in the stack, for source maps | | `url.full` | The page | | `url.template` | The route pattern, with the React Router integration | | `react.component_stack` | The component stack, from React | | `session.id` | The session, on every log and span | | `user.id`, `user.email`, `user.name` | From `setUser`, on every log and span | The SDK also sends: * Spans for `fetch` and `XMLHttpRequest` calls, which appear in [Traces](/telemetry/traces). * Logs for page loads and navigations, page load timing, and Web Vitals (LCP, INP, CLS, FCP, and TTFB). These errors are dropped before sending: * `Script error.` without details, and the ResizeObserver loop notice. * Errors whose frames all come from browser extensions or from `denyUrls`. * Errors that match `ignoreErrors`. * The same error repeated within a second. * Errors past 30 per minute. Change this with `maxErrorsPerMinute`. # Instrument your app Source: https://docs.superlog.sh/guides/instrument-your-app Create an ingest key and send logs, traces, and metrics from your app with the OpenTelemetry SDK. > [!NOTE] > > Telemetry is in early access. To turn it on for your workspace, [book a call](https://cal.com/superlog/yc) or ask in [Discord](https://discord.gg/wJ56aRh8hx). Superlog accepts standard OpenTelemetry over OTLP/HTTP. Your app sends logs, traces, and metrics with an ingest key. ## Create an ingest key **1. Open the OpenTelemetry setup** Open **Overview** in the sidebar. On a workspace with no telemetry, click **Set up OpenTelemetry**. Otherwise click **Add telemetry** and pick **OpenTelemetry**. If the page says **Sending telemetry is not available**, telemetry is not turned on for your workspace yet. **2. Create the key** Click **Create ingest key**, then **Copy key**. Keys start with `sl_ingest_`. You can see the key only once. Store it in your secret manager. You can find and revoke it later in **Settings → Ingest keys**. An agent with the [Superlog MCP server](/assistants/claude) can also create a key with `create_ingest_key`. To have a coding agent instrument your project, copy the prompt under **Paste this prompt into your coding agent** and paste it into Claude Code, Codex, Cursor, or another agent. The prompt includes your key. It tells the agent to add the OpenTelemetry SDK with automatic instrumentation, set `service.name` and `deployment.environment.name`, connect your logger, and read the key from the environment. To do it yourself, continue below. ## Configure the SDK Every OpenTelemetry SDK reads the same environment variables. Set these wherever your app runs: ```bash theme={null} export OTEL_EXPORTER_OTLP_ENDPOINT=https://superlog.sh/api/ingest export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf export OTEL_EXPORTER_OTLP_HEADERS=x-api-key= export OTEL_SERVICE_NAME=checkout-api export OTEL_RESOURCE_ATTRIBUTES=deployment.environment.name=production ``` * Use the endpoint for your workspace's region: `https://superlog.sh/api/ingest` for EU or `https://us.superlog.sh/api/ingest` for US. * The SDK adds `/v1/logs`, `/v1/traces`, and `/v1/metrics` to the endpoint. * `OTEL_SERVICE_NAME` sets `service.name`, which Superlog uses to group your data by service. * Superlog also accepts the key as `Authorization: Bearer `. Read the key from your secret manager. Do not commit it. ## Language setup The examples below use each language's standard automatic instrumentation. The Node.js, Python, and Java examples set the traces, metrics, and logs exporters to `otlp` so all three signals are sent. **Node.js** Install the SDK and the automatic instrumentations: ```bash theme={null} npm install @opentelemetry/api @opentelemetry/auto-instrumentations-node ``` Start your app with the instrumentation loaded first: ```bash theme={null} export OTEL_TRACES_EXPORTER=otlp export OTEL_METRICS_EXPORTER=otlp export OTEL_LOGS_EXPORTER=otlp export NODE_OPTIONS="--require @opentelemetry/auto-instrumentations-node/register" node app.js ``` This instruments HTTP, common web frameworks, database clients, and the `pino`, `winston`, and `bunyan` loggers. To send `winston` records, also install `@opentelemetry/winston-transport`. **Python** Install the distro and the OTLP exporter, then install instrumentations for the libraries your app uses: ```bash theme={null} pip install opentelemetry-distro opentelemetry-exporter-otlp opentelemetry-bootstrap -a install ``` Run your app through `opentelemetry-instrument`: ```bash theme={null} export OTEL_TRACES_EXPORTER=otlp export OTEL_METRICS_EXPORTER=otlp export OTEL_LOGS_EXPORTER=otlp export OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED=true opentelemetry-instrument python app.py ``` `OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED` sends records from the standard `logging` module, with their trace and span IDs. **Go** Go has no automatic agent. Set up the SDK in code with `autoexport`, which builds the exporters from the environment variables above: ```bash theme={null} go get go.opentelemetry.io/otel \ go.opentelemetry.io/otel/sdk \ go.opentelemetry.io/otel/sdk/metric \ go.opentelemetry.io/otel/sdk/log \ go.opentelemetry.io/otel/log \ go.opentelemetry.io/contrib/exporters/autoexport \ go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp \ go.opentelemetry.io/contrib/bridges/otelslog ``` ```go theme={null} package main import ( "context" "errors" "go.opentelemetry.io/contrib/exporters/autoexport" "go.opentelemetry.io/otel" "go.opentelemetry.io/otel/log/global" "go.opentelemetry.io/otel/propagation" sdklog "go.opentelemetry.io/otel/sdk/log" sdkmetric "go.opentelemetry.io/otel/sdk/metric" sdktrace "go.opentelemetry.io/otel/sdk/trace" ) // setupOTel starts traces, metrics, and logs. Call the returned function on exit. func setupOTel(ctx context.Context) (func(context.Context) error, error) { spans, err := autoexport.NewSpanExporter(ctx) if err != nil { return nil, err } tracerProvider := sdktrace.NewTracerProvider(sdktrace.WithBatcher(spans)) otel.SetTracerProvider(tracerProvider) otel.SetTextMapPropagator(propagation.NewCompositeTextMapPropagator( propagation.TraceContext{}, propagation.Baggage{}, )) metrics, err := autoexport.NewMetricReader(ctx) if err != nil { return nil, err } meterProvider := sdkmetric.NewMeterProvider(sdkmetric.WithReader(metrics)) otel.SetMeterProvider(meterProvider) logs, err := autoexport.NewLogExporter(ctx) if err != nil { return nil, err } loggerProvider := sdklog.NewLoggerProvider(sdklog.WithProcessor(sdklog.NewBatchProcessor(logs))) global.SetLoggerProvider(loggerProvider) return func(ctx context.Context) error { return errors.Join(tracerProvider.Shutdown(ctx), meterProvider.Shutdown(ctx), loggerProvider.Shutdown(ctx)) }, nil } ``` The SDK reads `OTEL_SERVICE_NAME` and `OTEL_RESOURCE_ATTRIBUTES` on its own, and `autoexport` sends all three signals over OTLP by default. Wrap HTTP handlers with `otelhttp.NewHandler` and create loggers with `otelslog.NewLogger` so requests become spans and `slog` records carry trace IDs. Call the returned shutdown function before the process exits, or the last batch is lost. **Java** Download the OpenTelemetry Java agent: ```bash theme={null} curl -L -o opentelemetry-javaagent.jar \ https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/latest/download/opentelemetry-javaagent.jar ``` Start your app with the agent: ```bash theme={null} export OTEL_TRACES_EXPORTER=otlp export OTEL_METRICS_EXPORTER=otlp export OTEL_LOGS_EXPORTER=otlp java -javaagent:opentelemetry-javaagent.jar -jar app.jar ``` The agent instruments common frameworks and clients, and sends Logback and Log4j records with their trace and span IDs. ## Check that data arrives Start your app and send it a few requests. Then open **Logs** and **Traces** in the sidebar. Your service appears under its `service.name`. In **Settings → Ingest keys**, the key shows **Used just now**. ## Other ways to send telemetry See [Collect telemetry](/collect-telemetry/overview) for the OpenTelemetry Collector, Vercel, AWS CloudWatch, Google Cloud, and the browser SDK. # Migrate from Datadog Source: https://docs.superlog.sh/guides/migrate/datadog Map Datadog features to Superlog, send your telemetry with OpenTelemetry, run both side by side, and recreate dashboards and monitors. > [!NOTE] > > Telemetry is in early access. To turn it on for your workspace, [book a call](https://cal.com/superlog/yc) or ask in [Discord](https://discord.gg/wJ56aRh8hx). Superlog receives logs, traces, and metrics as OpenTelemetry over OTLP/HTTP. To move from Datadog, you send your telemetry in that form, run both tools while you compare, and rebuild the dashboards and monitors you need. ## Concept map | Datadog | Superlog | | - | - | | Log Management | [Logs](/telemetry/logs) | | APM traces | [Traces](/telemetry/traces) | | Metrics | [Metrics](/telemetry/metrics) | | Dashboards and template variables | [Dashboards](/telemetry/dashboards) and variables | | Error Tracking | [Errors](/telemetry/errors) | | Monitors | [Alerts](/telemetry/alerts) | | Synthetic API tests (HTTP) | [Synthetic checks](/telemetry/synthetics) | | Datadog Terraform provider | [Superlog Terraform provider](/developer/terraform) | Superlog alerts compare a log count, span measure, or metric with a threshold, and notify Slack. Rewrite anomaly, forecast, and composite monitors as thresholds, or leave them out. Not covered: SLOs, profiling, security products, and notebooks have no Superlog equivalent. Superlog does not import Datadog dashboards or monitors. ## Move your data Create an ingest key first. See [Create an ingest key](/guides/instrument-your-app#create-an-ingest-key). ### If you already use OpenTelemetry Point your SDKs at Superlog: ```bash theme={null} export OTEL_EXPORTER_OTLP_ENDPOINT=https://superlog.sh/api/ingest export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf export OTEL_EXPORTER_OTLP_HEADERS=x-api-key= ``` If you run a Collector, add an exporter and list it in each pipeline: ```yaml theme={null} exporters: otlphttp/superlog: endpoint: https://superlog.sh/api/ingest headers: x-api-key: ${env:SUPERLOG_INGEST_KEY} ``` Superlog accepts OTLP over HTTP only, so use the HTTP exporter, not the gRPC `otlp` exporter. See [OpenTelemetry Collector](/collect-telemetry/opentelemetry-collector). ### If you use Datadog tracing libraries The OpenTelemetry Collector Contrib distribution has a [`datadog` receiver](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/datadogreceiver). It accepts traces from Datadog tracing libraries on the Datadog Agent's trace API and converts them to OpenTelemetry. > [!WARNING] > > The `datadog` receiver is alpha for traces and in development for metrics and logs. Its behavior can change between Collector releases. Use it as a bridge while you move to OpenTelemetry SDKs. ```yaml theme={null} receivers: datadog: endpoint: 0.0.0.0:8126 read_timeout: 60s exporters: otlphttp/superlog: endpoint: https://superlog.sh/api/ingest headers: x-api-key: ${env:SUPERLOG_INGEST_KEY} service: pipelines: traces: receivers: [datadog] exporters: [otlphttp/superlog] ``` Point your tracers at the Collector with `DD_TRACE_AGENT_URL=http://:8126`. This setting takes precedence over `DD_AGENT_HOST` and `DD_TRACE_AGENT_PORT`. The Collector now takes the Agent's place for traces. To keep sending them to Datadog, add the Datadog exporter from the next section. The receiver sets `service.name`, `deployment.environment.name`, and `service.version` from the tracer's service, env, and version. Spans the tracer marks as errors keep an error status. [Errors](/telemetry/errors) reads `exception` span events and error logs, so check that these services show up there before you rely on it. The receiver also accepts metrics and logs in the Datadog Agent's formats. See its README for the endpoints and caveats. Over time, replace the Datadog tracing libraries with OpenTelemetry SDKs. See [Instrument your app](/guides/instrument-your-app). ## Run both side by side A Collector can send the same data to Datadog and Superlog. The Datadog exporter and connector are in Collector Contrib and are beta. The [connector](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/connector/datadogconnector) is required for services to appear in Datadog APM. ```yaml theme={null} receivers: otlp: protocols: grpc: endpoint: 0.0.0.0:4317 http: endpoint: 0.0.0.0:4318 connectors: datadog/connector: exporters: datadog: api: site: ${env:DD_SITE} key: ${env:DD_API_KEY} otlphttp/superlog: endpoint: https://superlog.sh/api/ingest headers: x-api-key: ${env:SUPERLOG_INGEST_KEY} service: pipelines: traces: receivers: [otlp] exporters: [datadog/connector, datadog, otlphttp/superlog] metrics: receivers: [otlp] exporters: [datadog, otlphttp/superlog] metrics/datadog-apm: receivers: [datadog/connector] exporters: [datadog] logs: receivers: [otlp] exporters: [datadog, otlphttp/superlog] ``` Set `DD_SITE` to your Datadog site, such as `datadoghq.com` or `datadoghq.eu`. The `metrics/datadog-apm` pipeline sends the connector's APM stats to Datadog only. To use the `datadog` receiver from the previous section, add it to the `traces` pipeline's receivers. ## Recreate dashboards and monitors An AI agent can read your Datadog dashboards and monitors and build them in Superlog. Use Claude Code or another MCP client with two servers connected: * **Datadog MCP server.** See [Datadog's setup guide](https://docs.datadoghq.com/mcp_server/setup/) for your site and client. Its default `core` toolset covers monitors and dashboards. * **Superlog MCP server.** See [MCP server](/api-reference/mcp). Then give the agent a prompt like this: ```text theme={null} Read the Datadog dashboard "Checkout overview" and every monitor tagged team:checkout. For each dashboard widget, find the matching Superlog data with list_services, query_metrics, query_traces, and query_logs. Create a Superlog dashboard with create_dashboard and add each widget with add_dashboard_widget. For each monitor, draft a Superlog alert and check it with preview_alert. Show me the rule, threshold, and preview result before you call create_alert. List every widget and monitor you could not map, and why. ``` Check the result before you trust it: * Review each alert's `preview_alert` result and threshold. * Open each dashboard and compare it with Datadog over the same time range. * Expect name changes. Metrics from Datadog integrations and from OpenTelemetry instrumentation often have different names and units. When the dashboards and alerts look right, ask the agent to call `export_terraform` and commit the output. See [Terraform](/developer/terraform). While you run both, Superlog automations can also read Datadog through the [Datadog integration](/integrations/datadog). ## Attribute mapping Datadog's unified service tags map to OpenTelemetry resource attributes: | Datadog tag | Datadog variable | OpenTelemetry attribute | | - | - | - | | `service` | `DD_SERVICE` | `service.name` | | `env` | `DD_ENV` | `deployment.environment.name` | | `version` | `DD_VERSION` | `service.version` | OpenTelemetry SDKs don't read the `DD_*` variables. Set the attributes with the standard variables: ```bash theme={null} export OTEL_SERVICE_NAME=checkout-api export OTEL_RESOURCE_ATTRIBUTES=deployment.environment.name=production,service.version=1.4.2 ``` Use `deployment.environment.name`. The older `deployment.environment` is deprecated. Move other `key:value` tags you filter on, such as `team:checkout`, into `OTEL_RESOURCE_ATTRIBUTES` as `team=checkout`. ## Cutover checklist * Every service appears in Superlog with the right `service.name` and environment. * Logs carry trace and span IDs. * Each dashboard you need exists and matches Datadog over the same time range. * Each alert has a previewed threshold and posts to the right Slack channel. * HTTP checks are recreated as [synthetic checks](/telemetry/synthetics). * Alerts, dashboards, and checks are exported to Terraform and committed. * Datadog monitors that duplicate Superlog alerts are muted. * The Datadog exporter is removed from the Collector, then the Datadog Agent and tracing libraries are removed. # Migrate from Dynatrace Source: https://docs.superlog.sh/guides/migrate/dynatrace Map Dynatrace features to Superlog, move to OpenTelemetry, send to both while you compare, and recreate dashboards and alerts. > [!NOTE] > > Telemetry is in early access. To turn it on for your workspace, [book a call](https://cal.com/superlog/yc) or ask in [Discord](https://discord.gg/wJ56aRh8hx). Superlog receives logs, traces, and metrics as OpenTelemetry over OTLP/HTTP. Dynatrace also accepts OTLP, so once your services use OpenTelemetry you can send the same data to both and compare before you switch. ## Concept map | Dynatrace | Superlog | | - | - | | Logs | [Logs](/telemetry/logs) | | Distributed traces | [Traces](/telemetry/traces) | | Metrics | [Metrics](/telemetry/metrics) | | Dashboards | [Dashboards](/telemetry/dashboards) | | Metric events and custom alerts | [Alerts](/telemetry/alerts) | | HTTP monitors | [Synthetic checks](/telemetry/synthetics) | Superlog has no query language like DQL. Charts and alerts are built from a data source, filters, a measure, and a group-by. Alerts compare that value with a threshold and notify Slack. [Errors](/telemetry/errors) groups the exceptions your OpenTelemetry SDKs record. Not covered: Davis problem detection and automatic baselines, Smartscape topology, notebooks, and notification destinations other than Slack. Superlog does not import Dynatrace dashboards or alerts. ## Move your data Create an ingest key first. See [Create an ingest key](/guides/instrument-your-app#create-an-ingest-key). ### If you already use OpenTelemetry Point your SDKs at Superlog: ```bash theme={null} export OTEL_EXPORTER_OTLP_ENDPOINT=https://superlog.sh/api/ingest export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf export OTEL_EXPORTER_OTLP_HEADERS=x-api-key= ``` If you run a Collector, add an exporter and list it in each pipeline: ```yaml theme={null} exporters: otlphttp/superlog: endpoint: https://superlog.sh/api/ingest headers: x-api-key: ${env:SUPERLOG_INGEST_KEY} ``` Superlog accepts OTLP over HTTP only, so use the HTTP exporter, not the gRPC `otlp` exporter. See [OpenTelemetry Collector](/collect-telemetry/opentelemetry-collector). ### If you use OneAgent OneAgent reports to Dynatrace in its own format. The OpenTelemetry Collector has no receiver for it, so the path is to replace OneAgent instrumentation with OpenTelemetry SDKs. See [Instrument your app](/guides/instrument-your-app). Move one service at a time: 1. Add the OpenTelemetry SDK with automatic instrumentation. 2. Send to a Collector that exports to both Dynatrace and Superlog, as shown below. The service keeps reporting to Dynatrace while you compare. 3. When the service's OpenTelemetry data in Dynatrace covers what you need, stop monitoring it with OneAgent. If OneAgent still runs on a host while the app exports OTLP, leave OneAgent's OpenTelemetry Span Sensor off. With both on, Dynatrace records duplicate spans. ## Run both side by side Dynatrace accepts OTLP over HTTP with protobuf, and only delta metrics. Superlog reads both delta and cumulative metrics. This config converts metrics to delta on the Dynatrace pipeline only: ```yaml theme={null} receivers: otlp: protocols: grpc: endpoint: 0.0.0.0:4317 http: endpoint: 0.0.0.0:4318 processors: cumulative_to_delta: exporters: otlphttp/dynatrace: endpoint: https://.live.dynatrace.com/api/v2/otlp headers: Authorization: "Bearer ${env:DT_PLATFORM_TOKEN}" otlphttp/superlog: endpoint: https://superlog.sh/api/ingest headers: x-api-key: ${env:SUPERLOG_INGEST_KEY} service: pipelines: traces: receivers: [otlp] exporters: [otlphttp/dynatrace, otlphttp/superlog] logs: receivers: [otlp] exporters: [otlphttp/dynatrace, otlphttp/superlog] metrics/dynatrace: receivers: [otlp] processors: [cumulative_to_delta] exporters: [otlphttp/dynatrace] metrics/superlog: receivers: [otlp] exporters: [otlphttp/superlog] ``` * The token is a Dynatrace platform token with `openpipeline:logs:ingest`, `openpipeline:metrics:ingest`, and `openpipeline:traces:ingest`. * Remove `.apps` from the environment ID if you copied it from the browser address bar. * To send through an Environment ActiveGate instead, see [Dynatrace's OTLP export guide](https://docs.dynatrace.com/docs/shortlink/api-otlp-ingest). * The conversion keeps state in the Collector. Send each service's metrics through the same Collector instance. You can skip the processor if your SDKs export delta with `OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE=delta`. > [!TIP] > > Collector Contrib releases before v0.157.0 name the processor `cumulativetodelta`. ## Recreate dashboards and alerts Dynatrace publishes a [remote MCP server](https://docs.dynatrace.com/docs/shortlink/dynatrace-mcp-server) that can generate and run DQL queries. An AI agent connected to it and to Superlog can run your Dynatrace queries and build matching charts and alerts in Superlog. Use Claude Code or another MCP client with two servers connected: * **Dynatrace MCP server.** See [Dynatrace's setup guide](https://docs.dynatrace.com/docs/shortlink/dynatrace-mcp-server). It authenticates with a platform token. * **Superlog MCP server.** See [MCP server](/api-reference/mcp). Copy the DQL from each dashboard tile and alert you want to keep. Then give the agent a prompt like this: ```text theme={null} Here are the DQL queries behind my Dynatrace "Checkout overview" dashboard and my checkout alerts: . Run each query in Dynatrace. Find the matching Superlog data with list_services, query_metrics, query_traces, and query_logs. Create a Superlog dashboard with create_dashboard and add a widget per query with add_dashboard_widget. Compare the numbers for the same time range. For each alert, draft a Superlog alert and check it with preview_alert. Show me the rule, threshold, and preview result before you call create_alert. List every query you could not map, and why. ``` Check the result before you trust it: * Review each alert's `preview_alert` result and threshold. * Open each dashboard and compare it with Dynatrace over the same time range. * Expect name changes. OneAgent metrics and OpenTelemetry metrics have different names. * Alerts that rely on Davis baselines need a fixed threshold. Use the preview to pick one. When the dashboards and alerts look right, ask the agent to call `export_terraform` and commit the output. See [Terraform](/developer/terraform). ## Attribute mapping | Dynatrace | OpenTelemetry | | - | - | | Service name | `service.name` | | `DT_RELEASE_STAGE` | `deployment.environment.name` | | `DT_RELEASE_VERSION` | `service.version` | ```bash theme={null} export OTEL_SERVICE_NAME=checkout-api export OTEL_RESOURCE_ATTRIBUTES=deployment.environment.name=production,service.version=1.4.2 ``` * Dynatrace uses `service.name` as the service name for OpenTelemetry services in Service Detection v2. Keep the old service name to make the two easy to compare. * If you set `deployment.release_stage` and `deployment.release_version` for Dynatrace, set `deployment.environment.name` and `service.version` as well. ## Cutover checklist * Every service appears in Superlog with the right `service.name` and environment. * No host runs the OneAgent Span Sensor alongside OTLP export. * Logs carry trace and span IDs. * Each dashboard you need exists and matches Dynatrace over the same time range. * Each alert has a previewed threshold and posts to the right Slack channel. * HTTP monitors are recreated as [synthetic checks](/telemetry/synthetics). * Alerts, dashboards, and checks are exported to Terraform and committed. * Dynatrace alerts that duplicate Superlog alerts are turned off. * The Dynatrace exporter is removed from the Collector, then OneAgent is removed. # Migrate from New Relic Source: https://docs.superlog.sh/guides/migrate/new-relic Map New Relic features to Superlog, move to OpenTelemetry, send to both while you compare, and recreate dashboards and alerts. > [!NOTE] > > Telemetry is in early access. To turn it on for your workspace, [book a call](https://cal.com/superlog/yc) or ask in [Discord](https://discord.gg/wJ56aRh8hx). Superlog receives logs, traces, and metrics as OpenTelemetry over OTLP/HTTP. New Relic also accepts OTLP, so once your services use OpenTelemetry you can send the same data to both and compare before you switch. ## Concept map | New Relic | Superlog | | - | - | | Logs | [Logs](/telemetry/logs) | | Distributed tracing | [Traces](/telemetry/traces) | | Metrics | [Metrics](/telemetry/metrics) | | Dashboards | [Dashboards](/telemetry/dashboards) | | Errors inbox | [Errors](/telemetry/errors) | | Alert policies and conditions | [Alerts](/telemetry/alerts) | | Ping synthetic monitors | [Synthetic checks](/telemetry/synthetics) | | New Relic Terraform provider | [Superlog Terraform provider](/developer/terraform) | Superlog has no query language like NRQL. Charts and alerts are built from a data source, filters, a measure, and a group-by. Alerts compare that value with a threshold and notify Slack. Not covered: scripted browser and scripted API monitors, anomaly detection, and notification destinations other than Slack. Superlog does not import New Relic dashboards or alert conditions. ## Move your data Create an ingest key first. See [Create an ingest key](/guides/instrument-your-app#create-an-ingest-key). ### If you already use OpenTelemetry Point your SDKs at Superlog: ```bash theme={null} export OTEL_EXPORTER_OTLP_ENDPOINT=https://superlog.sh/api/ingest export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf export OTEL_EXPORTER_OTLP_HEADERS=x-api-key= ``` If you run a Collector, add an exporter and list it in each pipeline: ```yaml theme={null} exporters: otlphttp/superlog: endpoint: https://superlog.sh/api/ingest headers: x-api-key: ${env:SUPERLOG_INGEST_KEY} ``` Superlog accepts OTLP over HTTP only, so use the HTTP exporter, not the gRPC `otlp` exporter. See [OpenTelemetry Collector](/collect-telemetry/opentelemetry-collector). ### If you use New Relic APM agents New Relic APM agents report to New Relic in their own format. The OpenTelemetry Collector has no receiver for it, so the path is to replace each agent with an OpenTelemetry SDK. See [Instrument your app](/guides/instrument-your-app). Move one service at a time: 1. Remove the New Relic agent from the service. New Relic does not guarantee its agents work alongside another APM product in the same process. 2. Add the OpenTelemetry SDK with automatic instrumentation. 3. Send to a Collector that exports to both New Relic and Superlog, as shown below. The service keeps reporting to New Relic while you compare. Some New Relic agents can capture spans you create with the OpenTelemetry API. This is off by default, and the agent still reports to New Relic, not over OTLP. It lets you write OpenTelemetry instrumentation before you remove the agent. See [OpenTelemetry API support in New Relic agents](https://docs.newrelic.com/docs/apm/agents/manage-apm-agents/opentelemetry-api-support/). ## Run both side by side ```yaml theme={null} receivers: otlp: protocols: grpc: endpoint: 0.0.0.0:4317 http: endpoint: 0.0.0.0:4318 exporters: otlphttp/newrelic: endpoint: https://otlp.nr-data.net headers: api-key: ${env:NEW_RELIC_LICENSE_KEY} otlphttp/superlog: endpoint: https://superlog.sh/api/ingest headers: x-api-key: ${env:SUPERLOG_INGEST_KEY} service: pipelines: traces: receivers: [otlp] exporters: [otlphttp/newrelic, otlphttp/superlog] metrics: receivers: [otlp] exporters: [otlphttp/newrelic, otlphttp/superlog] logs: receivers: [otlp] exporters: [otlphttp/newrelic, otlphttp/superlog] ``` * The `api-key` header takes your New Relic license key. * `https://otlp.nr-data.net` is the US endpoint. EU accounts use `https://otlp.eu01.nr-data.net`. For other regions, see [New Relic's OTLP endpoint list](https://docs.newrelic.com/docs/opentelemetry/best-practices/opentelemetry-otlp/). * New Relic rejects payloads over 1 MB and prefers delta temporality for counters and histograms. Superlog reads both delta and cumulative metrics, so `OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE=delta` in your SDKs works for both. ## Recreate dashboards and alerts New Relic publishes an [MCP server](https://docs.newrelic.com/docs/agentic-ai/mcp/overview/). Its tools include `list_dashboards`, `get_dashboard`, `list_alert_policies`, `list_alert_conditions`, and `execute_nrql_query`. An AI agent connected to it and to Superlog can read your New Relic setup and build it in Superlog. Use Claude Code or another MCP client with two servers connected: * **New Relic MCP server.** See [New Relic's setup guide](https://docs.newrelic.com/docs/agentic-ai/mcp/setup/). The US endpoint is `https://mcp.newrelic.com/mcp/` and the EU endpoint is `https://mcp.eu.newrelic.com/mcp/`. * **Superlog MCP server.** See [MCP server](/api-reference/mcp). Then give the agent a prompt like this: ```text theme={null} Read the New Relic dashboard "Checkout overview" and the conditions in the alert policy "Checkout". For each widget, read its NRQL and run it with execute_nrql_query. Find the matching Superlog data with list_services, query_metrics, query_traces, and query_logs. Create a Superlog dashboard with create_dashboard and add each widget with add_dashboard_widget. Compare the numbers for the same time range. For each alert condition, draft a Superlog alert and check it with preview_alert. Show me the rule, threshold, and preview result before you call create_alert. List every widget and condition you could not map, and why. ``` Check the result before you trust it: * Review each alert's `preview_alert` result and threshold. * Open each dashboard and compare it with New Relic over the same time range. * Expect query changes. NRQL often reads New Relic event types such as `Transaction`. The agent has to map each one to OpenTelemetry spans or metrics. When the dashboards and alerts look right, ask the agent to call `export_terraform` and commit the output. See [Terraform](/developer/terraform). ## Attribute mapping | New Relic agent | OpenTelemetry | | - | - | | App name (`app_name`, `NEW_RELIC_APP_NAME`) | `service.name` | | Labels (`NEW_RELIC_LABELS`, such as `Env:Dev`) | Resource attributes in `OTEL_RESOURCE_ATTRIBUTES` | | Environment label | `deployment.environment.name` | | Host | `host.name` | ```bash theme={null} export OTEL_SERVICE_NAME=checkout-api export OTEL_RESOURCE_ATTRIBUTES=deployment.environment.name=production,service.version=1.4.2 ``` * New Relic shows OpenTelemetry services under their `service.name`. Keep the old app name to make the two easy to compare. * A New Relic app can have up to three names. `service.name` takes one value. * SDK resource detectors and the Collector's `resourcedetection` processor set `host.name`. * Set `service.version` too, so you can tell deploys apart. ## Cutover checklist * Every service appears in Superlog with the right `service.name` and environment. * No service runs a New Relic agent and OpenTelemetry instrumentation in the same process. * Logs carry trace and span IDs. * Each dashboard you need exists and matches New Relic over the same time range. * Each alert has a previewed threshold and posts to the right Slack channel. * Ping monitors are recreated as [synthetic checks](/telemetry/synthetics). * Alerts, dashboards, and checks are exported to Terraform and committed. * New Relic alert conditions that duplicate Superlog alerts are disabled. * The New Relic exporter is removed from the Collector. # Triage Sentry issues into pull requests Source: https://docs.superlog.sh/guides/triage-sentry-issues Set up an automation that rates each new Sentry issue, posts a summary to Slack, and opens a pull request with the fix. This guide sets up an automation that runs on each new Sentry issue. The agent rates the issue, finds the cause in your code, posts a short summary to Slack, and opens a pull request with the fix. False alarms are not posted. ## Before you start You need: * [Sentry](/integrations/sentry) connected, with the projects you want to watch. * [GitHub](/integrations/github) connected, with the GitHub App granted access to the repositories behind those projects. * [Slack](/integrations/slack) connected, if you want the summary in a channel. Connect them under **Integrations**, or from the automation editor when the template asks for them. ## Create the automation **1. Pick the template** Open **Automations**. Under **Start from a template**, filter by **Bug triage** and click **Alert on critical Sentry issues**. The editor opens with the trigger, instructions, and the Sentry, GitHub, and Slack connectors filled in. See [Templates](/automations/templates). **2. Choose the Sentry projects** The template adds a Sentry **New issue** trigger. Under **Project**, pick the projects to watch, up to 100. **3. Exclude environments** Under **Environment**, clear the environments that should not start a run, such as `staging` or `development`. The default is **All environments**. Environments that appear in Sentry later are included. **4. Add repositories** Under **Repositories**, click **Add repository** and pick the code behind the projects. The first one is the agent's working directory. **5. Add a Slack channel** Under **Notifications**, click **Add notification**, then **Post to Slack**, and pick the channel for the summaries. **6. Choose a model and save** Click **Choose model** in the instructions toolbar, pick a model, then click **Save**. See [Models and harnesses](/automations/models). ## Trigger options The Sentry trigger has three events: | Event | Use it when | | - | - | | **New issue** | You want each new error triaged. This is the template's default. | | **Issue regression** | You only care about resolved issues that come back. The **Fix regressions** template is built for this. | | **New issue or regression** | You want both. | To narrow what starts a run, select fewer projects or exclude more environments. See [Triggers](/automations/triggers#sentry). ## Adjust the instructions The template tells the agent to: 1. Rate the issue from SEV-1 to SEV-3, and stay quiet on a complete false positive. 2. Post a short message with the severity, what broke, the suspected commit and author, and who is affected. 3. Add the root cause and proposed fix in the thread, open a pull request, and link it there. Edit the instructions under **Agent instructions** to match your team. For example, change the severity scale, say which errors are known noise, or tell the agent to skip the pull request for some services. ## What a run does Each new issue starts one run, titled with the Sentry short ID and the issue title. The run gets a fresh sandbox with your repositories checked out. The agent receives the issue details and can read more events and traces through the Sentry connector. The agent can post to the notification channel during the run. If it does not, its final message is posted there with a **View run** link. When the agent decides an issue is not worth reporting, it skips the notification, and the run page shows the reason. A failed run is always reported. When the agent opens a pull request, it appears as a card in the run and on the **PRs** page. See [Runs](/automations/runs) and [Pull requests](/automations/pull-requests). ## Review the pull request Pull requests open without an approval step. Use your branch protection and review rules as the gate before merge. To ask for changes, submit a review on GitHub. The review continues the run that opened the pull request. The agent checks each comment, pushes fixes to the same branch, and replies to each comment. You can also send a follow-up from the run page. See [Follow-ups from GitHub reviews](/automations/pull-requests#follow-ups-from-github-reviews). ## Test it Click **Test** in the automation header and paste a Sentry issue link or the error details. Your message is treated as the trigger event, so you can check the agent's output before real issues arrive. # Superlog Source: https://docs.superlog.sh/index Reliability for the AI era We're building the world's cheapest, most performant monitoring system, designed to be easy for agents to install and configure. Superlog helps teams build self-healing systems by connecting their agents to telemetry and running automations that detect and remediate issues at machine speed. ## Get started > **[Instrument your app](/guides/instrument-your-app)** > > Send logs, traces, and metrics with OpenTelemetry. > **[Browser and React](/guides/browser)** > > Capture errors, traces, and Web Vitals from the browser. > **[Install Superlog MCP](/assistants/claude)** > > Manage your workspace from Claude, Cursor, or Codex. > **[Automations](/automations/overview)** > > See what automations can do with your code and tools. ## What teams automate > **[Bug triage](/automations/templates#bug-triage)** > > Rate new Sentry issues, trace them to the commit that caused them, and open a pull request when the fix is small. > **[Internal support](/automations/templates#support)** > > Answer "is this a bug?" and "can we do this?" questions in Slack from the code and docs, so engineers are not interrupted. > **[Reliability checks](/automations/templates#scans)** > > Compare the last hour against the past week in Sentry and Datadog, and post to Slack only when something is out of range. > **[Observability and performance reviews](/automations/templates#scans)** > > Find code paths with poor telemetry and slow endpoints each week, and open pull requests that fix them. ## Telemetry Superlog also stores your OpenTelemetry logs, traces, and metrics. You can search them, build dashboards, group exceptions into issues, and alert on them. Automations and agents read the same data. Telemetry is in early access. * [Collect telemetry](/collect-telemetry/overview) from your code, a Collector, Vercel, AWS, or Google Cloud. * [Make your application reliable](/reliability/checklist) with error notifications, alerts, synthetic checks, dashboards, and automations. ## Move from another tool > **[Datadog](/guides/migrate/datadog)** > > Send the same data to both, then recreate monitors and dashboards. > **[New Relic](/guides/migrate/new-relic)** > > Move OpenTelemetry data and rebuild alerts. > **[Dynatrace](/guides/migrate/dynatrace)** > > Move OpenTelemetry data and rebuild alerts. ## Bring your own inference Every automation picks a model from OpenAI, Anthropic, Google Gemini, xAI, Mistral, or DeepSeek, and runs it in the Codex, Claude Agent SDK, or OpenCode harness. Add an API key or connect a ChatGPT subscription and runs use it. Without one, runs use the usage included in your plan. See [Models and harnesses](/automations/models). ## Open source Superlog is open source under the Apache License 2.0. The code is at [superloglabs/responder-oss](https://github.com/superloglabs/responder-oss). Use the hosted service at [superlog.sh](https://superlog.sh), or [run it yourself](/self-hosting/overview). ## Get help * Ask in [Discord](https://discord.gg/wJ56aRh8hx). * [Book a call](https://cal.com/superlog/yc) with the team. # AWS and Google Cloud Source: https://docs.superlog.sh/integrations/cloud Give tag mode read-only access to your AWS account and Google Cloud projects with short-lived credentials. Connect AWS and Google Cloud so tag mode can inspect alarms, metrics, logs, and resources when it answers questions. Both use short-lived credentials. Superlog never stores long-lived cloud keys. Automations cannot use AWS or Google Cloud as connectors. CloudWatch alarms can still start automations through Slack. See [AWS alarms in Slack](#aws-alarms-in-slack). ## AWS Superlog connects to AWS with an IAM role you create from a CloudFormation template. It assumes the role through STS for each request. ### What Superlog can read The role uses the AWS-managed `AIOpsAssistantPolicy`, which grants read access across the account, including: * CloudWatch alarms, alarm history, metrics, and Logs Insights * SQS queue attributes * Lambda configuration and event source mappings * Other read-only AWS API calls An explicit deny blocks reading Secrets Manager values and SSM parameters, and decrypting with KMS. ### Connect AWS **1. Open the AWS dialog** In **Integrations**, click **Add** on AWS and enter your 12-digit **AWS account ID**. **2. Create the stack** Click **Create stack** to open AWS CloudFormation with the template. Review the role and policy, create the stack, and wait until its status is `CREATE_COMPLETE`. **3. Verify** Return to Superlog and click **Verify connection**. Superlog assumes the role to confirm it works. > [!WARNING] > > `AIOpsAssistantPolicy` grants read access in every region of the account. Review the template before you create the stack. Only the commercial AWS partition is supported. ### AWS alarms in Slack AWS does not send webhooks to Superlog. Send CloudWatch alarms to a Slack channel with Amazon Q Developer in chat applications. Then: * Add a Slack **New message in channel** trigger on that channel to start an automation, or * Mention Superlog in the alarm's thread to investigate it with tag mode. Superlog acts only on `ALARM` notifications. `OK` and `INSUFFICIENT_DATA` notifications are ignored. ## Google Cloud Superlog connects to Google Cloud with Workload Identity Federation in your project. It exchanges a short-lived identity for a Google token and impersonates a dedicated service account. No service account key is created. ### What Superlog can read Setup creates a `responder-investigation` service account with these roles: | Role | Access | | - | - | | MCP Tool User | Use Google's managed MCP servers | | Cloud Asset Viewer | Read Cloud Asset Inventory | | Logs Viewer | Query Cloud Logging | | Monitoring Viewer | Read Cloud Monitoring | | Service Usage Consumer | Check which APIs are enabled | Superlog uses only tools that Google's managed MCP servers mark as read-only. ### Connect Google Cloud **1. Sign in with Google** In **Integrations**, click **Add** on Google Cloud, then **Continue with Google**. Use an account that can enable APIs, create service accounts and workload identity pools, and change project IAM. **2. Choose a project** Pick the project and click **Grant read-only access**. **3. Wait for setup** Setup runs in the background and can take up to 15 minutes. It enables the required APIs, creates the service account, and configures Workload Identity Federation. You can close the window. The Google Cloud card shows the progress. Superlog uses your Google sign-in only for setup and revokes it afterwards. To connect more projects, open **Manage** on the Google Cloud card and click **Add project**. **Remove** disconnects a project from Superlog. It does not delete the service account or IAM bindings in your project. # Custom MCP servers Source: https://docs.superlog.sh/integrations/custom-mcp Connect any remote MCP server so automations and tag mode can use its tools. Connect your own remote MCP server to give agents tools Superlog does not have built in, such as an internal admin API or a data source you host. ## Requirements * The server uses the Streamable HTTP transport. * The URL uses HTTPS and resolves to a public address. * Authentication is an API token, or OAuth 2.0 with authorization-server discovery, PKCE, and dynamic client registration. ## Add a server **1. Open the dialog** In **Integrations**, click **Add** on **Custom MCP**. Or, in the automation connector picker, click **Add custom MCP server**. **2. Enter the server details** Enter a **Name** and the **Streamable HTTP URL**. **3. Choose authentication** Choose **API token** and paste the token, or choose **OAuth 2.0** and click **Continue with OAuth** to approve access on your server. For OAuth, Superlog registers a client on your server with this redirect URL: ```text theme={null} https://superlog.sh/api/integrations/custom_mcp/callback ``` On a self-hosted deployment, use your own public URL instead. ## Tool access Superlog passes every tool the server exposes to the agent. It does not filter them to read-only, so the agent can call write tools if the server has them. Expose only the tools you want agents to use, and write clear tool descriptions so the agent knows when to call them. Your server receives every call the agent makes. Use its logs to audit what agents did. Redirects are checked again before they are followed, and authorization is never forwarded to another origin. # Datadog Source: https://docs.superlog.sh/integrations/datadog Connect Datadog with API and application keys so agents can read logs, metrics, monitors, and traces. Datadog gives agents your logs, metrics, monitors, and traces. Datadog alerts can start automations through a Slack channel. ## Connect Datadog **1. Create keys in Datadog** In Datadog, create an API key and an application key. Scope the application key to the data you want Superlog to read. **2. Add Datadog in Superlog** In **Integrations**, click **Add** on Datadog. Choose your Datadog site, paste the **API key** and **Application key**, and click **Connect Datadog**. | Site | Domain | | - | - | | US1 | `app.datadoghq.com` | | US3 | `us3.datadoghq.com` | | US5 | `us5.datadoghq.com` | | EU1 | `app.datadoghq.eu` | | AP1 | `ap1.datadoghq.com` | | AP2 | `ap2.datadoghq.com` | | UK1 | `uk1.datadoghq.com` | Choose the site your account uses. A wrong site means queries find no data. ## Let agents read Datadog Add Datadog as a connector. The agent uses Datadog's MCP server for your site. Superlog passes its tools through without filtering, so the application key's scope is the limit on what the agent can do. The **Reliability check**, **Review observability**, **Review performance**, and **Fix regressions** templates use Datadog. See [Templates](/automations/templates). ## Start automations from Datadog alerts Send Datadog monitor notifications to a Slack channel. Then add a Slack **New message in channel** trigger on that channel. Recovery notifications are ignored. No Datadog webhook is needed. ## Tag mode Tag mode can read Datadog when you turn it on for tag mode. # Discord Source: https://docs.superlog.sh/integrations/discord Connect Discord to start automations with the /automate command. Discord lets people in your server start automations with a slash command. The **Answer community questions** template uses it. ## Connect Discord In **Integrations**, click **Add** on Discord and authorize the Superlog app for one Discord server. Superlog syncs the server's text and announcement channels and registers the `/automate` command. If a new channel is missing from the trigger, reconnect Discord to refresh the channel list. ## Start automations from Discord **1. Add a Discord trigger** In the automation editor, click **Add trigger**, choose **Automation command in channel**, and pick the channels. **2. Run the command** In one of those channels, run `/automate`. Add the optional `context` option to pass text to the agent. ```text theme={null} /automate context: How do I rotate an API key? ``` `/automate` starts every active automation that watches the channel. Discord shows a private reply: **Automation started.**, or a message that no automation is configured for the channel. The agent's result is not posted back to Discord. Give the automation another way to report, such as a Slack connector or a GitHub repository for pull requests. ## Self-hosted setup Create a Discord application with a bot. Enable **Requires OAuth2 Code Grant** and grant the **View Channels** permission. | Setting | Value | | - | - | | OAuth redirect | `/api/integrations/discord/callback` | | Interactions endpoint | `/api/webhooks/discord` | Set `DISCORD_APPLICATION_ID`, `DISCORD_BOT_TOKEN`, `DISCORD_CLIENT_SECRET`, and `DISCORD_PUBLIC_KEY`. See [Environment variables](/self-hosting/environment). # GitHub Source: https://docs.superlog.sh/integrations/github Install the Superlog GitHub App so automations can check out your repositories and open pull requests. GitHub gives automations their code. Every automation checks out at least one repository, and with GitHub connected the agent can read pull requests, commits, and issues, and open pull requests with its changes. ## Connect GitHub **1. Start the install** In **Integrations**, click **Add** on GitHub. Or, in the automation editor, click **Add GitHub** under **Repositories**. **2. Install the app** GitHub opens the Superlog GitHub App install page. Choose the account or organization and the repositories to grant. **3. Pick repositories** Back in Superlog, the granted repositories appear in **Add repository**. To grant more, change the app's repository access in GitHub. ## What automations can do | Action | Details | | - | - | | Check out repositories | Up to 10 per automation, without git history. The first is the working directory. | | Read GitHub | Pull requests, commits, comparisons, issues, files, and users in the granted repositories. | | Fetch other refs | Bring another branch, tag, or pull request into the sandbox. | | Open a pull request | Creates a branch from the agent's changes and opens a pull request against the checked-out branch. | Pull requests open without an approval step. Use your branch protection and review rules as the gate before merge. The sandbox never holds GitHub credentials. Superlog uses a short-lived installation token outside the sandbox and copies only the automation's repositories into it. ## Tag mode Tag mode can read the repositories you select for it. It does not open pull requests. ## Self-hosted setup Self-hosted deployments need their own public GitHub App. | Setting | Value | | - | - | | OAuth redirect URI | `/api/integrations/github/callback` | | Webhook URL | `/api/webhooks/github` | | Webhook events | Pull request, Pull request review | | Repository permission | Access | | - | - | | Contents | Read and write | | Pull requests | Read and write | | Metadata | Read | | Actions | Read | | Checks | Read | | Commit statuses | Read | | Issues | Read | Also grant the account permission **Email addresses: Read**. Set `GITHUB_APP_ID`, `GITHUB_APP_SLUG`, `GITHUB_APP_PRIVATE_KEY`, `GITHUB_CLIENT_ID`, `GITHUB_CLIENT_SECRET`, and `GITHUB_WEBHOOK_SECRET`. See [Environment variables](/self-hosting/environment). # Linear Source: https://docs.superlog.sh/integrations/linear Connect Linear so agents can read issues and projects and create assigned issues. Linear lets agents check existing work before acting and file issues for what they find. ## Connect Linear In **Integrations**, click **Add** on Linear and approve access for your Linear workspace. ## Let agents use Linear Add Linear as a connector. The agent can: * Read issues, projects, teams, users, labels, and workflow states through Linear's read-only MCP server. * Create issues with a team, title, and Markdown description, and optionally an assignee, labels, priority, project, workflow state, and parent issue. Issue creation runs without an approval step. Each created issue appears on the run page with **View issue**. If a run retries the same request, Superlog does not create a duplicate. Use instructions to say when the agent should file an issue, which team it goes to, and who to assign it to. ## Tag mode Tag mode can read Linear when you turn it on for tag mode. It does not create issues. ## Self-hosted setup Create a Linear OAuth app with `read` and `write` scopes. | Setting | Value | | - | - | | OAuth callback | `/api/integrations/linear/callback` | Set `LINEAR_CLIENT_ID` and `LINEAR_CLIENT_SECRET`. See [Environment variables](/self-hosting/environment). # More integrations Source: https://docs.superlog.sh/integrations/more Connect Dash0, PostHog, Grafana, Axiom, ClickStack, Langfuse, Upstash, Supabase, and Vercel as read-only context for tag mode. These integrations give [tag mode](/tag-mode) read access to your telemetry, data, and deployments. Connect them from **Integrations** with **Add**, then turn them on in **Tag mode**. Automations cannot use these integrations as connectors. To reach one of these tools from an automation, connect it as a [custom MCP server](/integrations/custom-mcp) or call its API with a [workspace secret](/settings/workspace-secrets). Tools that post alerts to Slack can start automations through a Slack trigger. ## Dash0 **1. Copy the MCP endpoint** In Dash0, open **Organization settings → Endpoints → MCP** and copy the organization MCP endpoint URL. **2. Connect** In Superlog, click **Add** on Dash0, paste the **MCP endpoint URL**, and approve access in Dash0. Superlog exposes only Dash0 tools marked read-only, and blocks Agent0 delegation, so it does not use your Agent0 credits. ## PostHog Click **Add** on PostHog and approve access. Superlog reads analytics, error tracking, session replays, dashboards, and logs through PostHog's MCP server, limited to read-only tools. To act on PostHog alerts, send them to a Slack channel and add a Slack trigger on that channel. Resolved and recovered notifications are ignored. ## Grafana | Mode | Setup | | - | - | | **Grafana Cloud** | Enter your **Stack URL**, for example `https://acme.grafana.net`, and approve access. Superlog requests only read and query scopes. | | **Self-hosted Grafana** | Enter the **Grafana URL** and a **Service account token** for a service account with the Viewer role. The URL must be public HTTPS. | Superlog reads dashboards, data sources, Prometheus, Loki, Tempo, Pyroscope, and alerts. Write, admin, and provisioning tools are disabled. ## Axiom Click **Add** on Axiom and approve access. Superlog reads logs, traces, metrics, dashboards, and monitor history. Mutation tools are blocked. Axiom's hosted MCP server routes query results through US infrastructure. Check Axiom's data routing and query cost settings before connecting sensitive or large datasets. ## ClickStack Click **Add** on **ClickStack / HyperDX** and choose a mode: | Mode | Setup | | - | - | | **ClickStack Cloud** | Enter the **MCP URL** and **ClickHouse service ID**, then approve access with ClickHouse Cloud. | | **Self-hosted** | Enter the public HTTPS **MCP URL** and a **Personal API Access Key**. | ## Langfuse In Langfuse, open **Project Settings → API Keys** and copy the public and secret keys. In Superlog, click **Add** on Langfuse, choose the deployment (Cloud EU, US, Japan, HIPAA US, or Self-hosted), and paste the **Project public key** and **Project secret key**. Each key pair belongs to one Langfuse project. Connect each project separately. Superlog reads traces, observations, scores, metrics, prompts, and alerts through an allowlist of read-only tools. ## Upstash In the Upstash console, create a developer API key for Superlog. In Superlog, click **Add** on Upstash and enter the **Account email** and **Developer API key**. Superlog reads Redis, Vector, Search, QStash, and Workflow resources. Write operations are blocked, and Redis commands are checked against a read-only allowlist. ## Supabase Click **Add** on Supabase, then **Continue with Supabase** and approve access. Choose a project, then an access level: | Access level | What it allows | | - | - | | **Logs only** | Project logs. No database access. | | **Logs and read-only data** | Adds SQL queries and schema inspection. Supabase enforces read-only mode. | | **Full database SQL access** | SQL that can change data or schema. Use only for development or test projects. | Each project and access level is a separate connection. Supabase administration and platform configuration tools stay blocked at every level. ## Vercel Click **Add** on Vercel and install the Superlog integration with read access to projects, deployments, deployment checks, domains, teams, logs, and security. Superlog does not request write access or access to environment variables, tokens, or secrets. In **Tag mode**, configure Vercel to choose which projects tag mode may read. # Integrations Source: https://docs.superlog.sh/integrations/overview Connect your alerts, code, and cloud to Superlog, and see which integrations automations and tag mode can use. Integrations connect Superlog to the tools you already use. Connect them once per workspace, then use them as automation triggers, as automation connectors, or as context for tag mode. ## Connect an integration Click **Integrations** in the sidebar. Find the tool under **Marketplace** and click **Add**. Depending on the tool, you approve access in the provider's sign-in page, paste an API key, or deploy a template in your cloud account. Connected tools move to **Connected integrations**, where **Manage** opens their settings. You can also connect a tool from the automation editor. Click **Connect** on a trigger or in the connector picker. Your draft stays open while you approve access. Credentials are encrypted before storage and scoped to your workspace. ## What each integration does | Integration | Automation trigger | Automation connector | Tag mode | | - | - | - | - | | [GitHub](/integrations/github) | — | Repositories, pull requests | Read-only code | | [Slack](/integrations/slack) | Messages and mentions | Read and post messages | Where questions are asked | | [Sentry](/integrations/sentry) | New issues and regressions | Read | Read | | [Datadog](/integrations/datadog) | Through Slack alerts | Read | Read | | [Linear](/integrations/linear) | — | Read, create issues | Read | | [Discord](/integrations/discord) | `/automate` command | — | — | | [Custom MCP](/integrations/custom-mcp) | — | All server tools | Read | | [AWS](/integrations/cloud#aws) | Through Slack alerts | — | Read | | [Google Cloud](/integrations/cloud#google-cloud) | — | — | Read | | [Dash0](/integrations/more#dash0) | — | — | Read | | [PostHog](/integrations/more#posthog) | Through Slack alerts | — | Read | | [Grafana](/integrations/more#grafana) | Through Slack alerts | — | Read | | [Axiom](/integrations/more#axiom) | — | — | Read | | [ClickStack / HyperDX](/integrations/more#clickstack) | — | — | Read | | [Langfuse](/integrations/more#langfuse) | — | — | Read | | [Upstash](/integrations/more#upstash) | — | — | Read | | [Supabase](/integrations/more#supabase) | — | — | Configurable | | [Vercel](/integrations/more#vercel) | — | — | Read | "Through Slack alerts" means the tool posts alerts to a Slack channel, and a Slack **New message in channel** trigger on that channel starts the run. ## How access is limited * Most built-in integrations expose only read-only tools, plus the write actions listed above. * Datadog and custom MCP servers pass their tools through without filtering. Supabase allows writes only if you choose **Full database SQL access**. Scope the credentials you give them. * Provider credentials stay outside the agent's sandbox. Superlog calls the provider on the agent's behalf. * If an integration cannot be reached during a run, the agent gets a reconnect tool with the error and decides whether to retry. The run continues. See [Security](/security) for more detail. # Sentry Source: https://docs.superlog.sh/integrations/sentry Connect Sentry to start automations on new issues and regressions, and let agents read issues, events, and traces. Sentry starts automations when errors appear and gives agents the issue details they need to find the cause. ## Connect Sentry In **Integrations**, click **Add** on Sentry and approve the Superlog app for your Sentry organization. Superlog syncs the projects your account can see. The Sentry card shows whether the connection works and how many projects it found. If a check fails, select the card to reconnect. ## Start automations from Sentry Add a Sentry trigger and pick up to 100 projects: * **New issue** when Sentry creates an issue. * **Issue regression** when a resolved issue comes back. * **New issue or regression** for both. The run is titled with the Sentry short ID and issue title. See [Triggers](/automations/triggers#sentry). The **Alert on critical Sentry issues** and **Fix regressions** templates are a good starting point. See [Templates](/automations/templates#bug-triage). ## Let agents read Sentry Add Sentry as a connector so the agent can look up issues, events, traces, and projects through Sentry's MCP server. This is useful for automations triggered from Slack or a schedule, such as matching a support report to a known error. Tag mode can read Sentry when you turn it on for tag mode. ## Self-hosted setup Self-hosted deployments need their own public Sentry integration. | Setting | Value | | - | - | | Redirect URL | `/api/integrations/sentry/callback` | | Webhook URL | `/api/webhooks/sentry` | | Resource subscriptions | `issue.created`, `issue.unresolved` | | Permissions | Organization: Read, Project: Read, Event: Read | | Verify install | Enabled | Set `SENTRY_APP_SLUG`, `SENTRY_CLIENT_ID`, and `SENTRY_CLIENT_SECRET`. Superlog checks every webhook signature against the client secret. See [Environment variables](/self-hosting/environment). # Slack Source: https://docs.superlog.sh/integrations/slack Connect Slack to start automations from messages and mentions, let agents post and reply, and use tag mode. Slack is where most teams talk to Superlog. Messages and mentions start automations, agents reply in threads and post to channels, and tag mode answers questions when someone mentions Superlog. ## Connect Slack In **Integrations**, click **Add** on Slack and approve the app in your Slack workspace. To watch or post in a private channel, invite the Superlog app to that channel first. ## Start automations from Slack Add a Slack trigger to an automation and pick the channels to watch: * **New message in channel** for alert channels and request channels. * **App mentioned** for requests addressed to Superlog. * **Message posted or app mentioned** for both. Tools that post alerts to Slack, such as Datadog, PostHog, Sentry, or AWS CloudWatch through Amazon Q Developer, can start runs this way. Recovery and resolved notifications from those tools are ignored. See [Triggers](/automations/triggers#slack). When a Slack message starts a run, Superlog posts a progress card in the thread. People can reply in the thread to continue the run. ## Let agents use Slack Add Slack as a connector to let the agent: * Search for channels, and read channels and threads. * Post messages and thread replies. * Add and remove reactions. Without the Slack connector, an agent started from Slack can read and reply only in its own thread. See [Connectors](/automations/connectors#slack). Scheduled automations can also post each finished run to Slack channels. See [Notifications](/automations/runs#notifications). ## Tag mode When tag mode is on, mentioning Superlog in any channel it can read starts a read-only investigation that replies in the thread. See [Tag mode](/tag-mode). ## Self-hosted setup Self-hosted deployments need their own distributed Slack app. Bot scopes: ```text theme={null} app_mentions:read channels:history channels:join channels:read chat:write chat:write.public groups:history groups:read reactions:write ``` User scope: ```text theme={null} search:read ``` | Setting | Value | | - | - | | OAuth redirect URL | `/api/integrations/slack/callback` | | Event subscriptions URL | `/api/webhooks/slack` | | Bot events | `app_mention`, `message.channels`, `message.groups` | | Interactivity URL | `/api/webhooks/slack/actions` | Set `SLACK_CLIENT_ID`, `SLACK_CLIENT_SECRET`, and `SLACK_SIGNING_SECRET`. See [Environment variables](/self-hosting/environment). # How Superlog works Source: https://docs.superlog.sh/overview How telemetry flows through Superlog: from your apps, into storage, to errors, alerts, dashboards, Slack, and agents. > [!NOTE] > > Telemetry is in early access. To turn it on for your workspace, [book a call](https://cal.com/superlog/yc) or ask in [Discord](https://discord.gg/wJ56aRh8hx). Your apps send logs, traces, and metrics to Superlog. Superlog stores them, groups exceptions into error issues, checks alerts and synthetic checks on a schedule, and posts to Slack when something is wrong. Agents read the same data through the MCP server and automations. Here is how a typical project uses Superlog to stay reliable: ![Telemetry flows from web apps, backend services, and cloud integrations into Superlog logs, traces, and metrics. Dashboards show the state of your system, alerts notify you when things break, and error fingerprinting helps discover new failure modes. Agents read the same telemetry. Synthetic checks monitor endpoint availability.](https://mintcdn.com/superlog/J5gnJHo6f9l7sX9w/images/how-superlog-works.png?fit=max\&auto=format\&n=J5gnJHo6f9l7sX9w\&q=85\&s=c15ba071c80e24715c19e290474a8d7e) Alerts, error notifications, and failing synthetic checks post to Slack. Agents read the same data through the MCP server and automations. ## 1. Your apps send telemetry Backend services send OpenTelemetry over OTLP/HTTP to your region's ingest endpoint with an ingest key. Browser apps send with the Superlog browser SDK. A Collector you already run can forward to the same endpoint. Vercel, AWS CloudWatch, and Google Cloud connect without code changes. The ingest key decides which workspace the data goes to. It can only add data. See [Collect telemetry](/collect-telemetry/overview). ## 2. Superlog stores it by service Every record keeps its resource attributes. `service.name` and `deployment.environment.name` are the ones Superlog groups and filters by. Each log record can carry the trace and span IDs of the request that wrote it, so you can go from a log line to its trace. When each service passes W3C trace context to the next, one user action becomes one trace, from the browser to every backend service and queue it reaches. ## 3. You explore it * [Logs](/telemetry/logs): search and filter log records. * [Traces](/telemetry/traces): find slow or failing requests and open a trace to see every span. * [Metrics](/telemetry/metrics): chart any metric your services send. * [Dashboards](/telemetry/dashboards): put the charts your team watches on one shared page. ## 4. Superlog detects problems | Feature | Reads | Tells you when | | - | - | - | | [Errors](/telemetry/errors) | Exception span events and error logs | A new error appears, or a resolved one comes back | | [Alerts](/telemetry/alerts) | A log count, span measure, or metric | The value crosses a threshold, and when it recovers | | [Synthetic checks](/telemetry/synthetics) | Requests Superlog sends to your URLs | An endpoint fails or is too slow, and when it passes again | Errors work without setup: exceptions are grouped into issues as they arrive. Alerts and synthetic checks are rules you create. ## 5. Your team hears about it in Slack Error notifications, alerts, and synthetic checks post to the Slack channels you choose. Recoveries reply in the same thread. You can resolve or silence an error from its Slack message. ## 6. Agents investigate * **MCP server.** Claude Code, Cursor, Codex, and other agents query your logs, traces, and metrics, read error issues, and create dashboards, alerts, and checks. See [Install Superlog MCP](/assistants/claude). * **Automations.** An automation can start on a new or regressed error, or on an alert or check message in a Slack channel it watches. It runs a coding agent with your repositories, finds the cause, and can open a pull request. See [Automations](/automations/overview). ## Where to start > **[Instrument your app](/guides/instrument-your-app)** > > Create an ingest key and send your first data. > **[Make your application reliable](/reliability/checklist)** > > Set up dashboards, alerts, and notifications with one prompt. # Make your application reliable Source: https://docs.superlog.sh/reliability/checklist Set up telemetry, connected traces, dashboards, alerts, error notifications, and synthetic checks with one agent prompt, one prompt per step, or by hand. > [!NOTE] > > Telemetry is in early access. To turn it on for your workspace, [book a call](https://cal.com/superlog/yc) or ask in [Discord](https://discord.gg/wJ56aRh8hx). You can set everything up with one prompt to a coding agent, or work through the [checklist](#checklist) one step at a time, by hand or with that step's prompt. ## Set it up with one prompt **1. Connect the agent to Superlog** Install the [Superlog MCP server](/assistants/claude) in Claude Code, Cursor, Codex, or another agent, and open it in your repository. Sign in as a workspace owner or admin, so the agent can turn on error notifications. **2. Create an API key for source maps** If you have a browser app, create a workspace API key under **Settings → API keys** and set it as `SUPERLOG_API_KEY` in your shell. The build uses it to upload source maps. The agent creates the ingest keys itself. **3. Paste the prompt** Paste the prompt below. For a workspace in the US region, replace `https://superlog.sh` with `https://us.superlog.sh`. The agent stops and asks you when it needs you to deploy, approve a connection, or choose a channel. ```text Setup prompt theme={null} Set up Superlog for this repository so the team knows about every failure that affects users. Superlog is at https://superlog.sh and you have its MCP server. A workspace API key for source map uploads may be in SUPERLOG_API_KEY. Never commit a key. This repository or workspace may already be partly or fully set up. Before each step, check what already exists. Keep what works and add only what is missing. Never delete, rename, rotate, or replace existing instrumentation, ingest keys, notification settings, dashboards, alerts, or synthetic checks. If you think an existing one should change, list the change and wait for my approval. Running this prompt again on a finished setup should change nothing. Work in these steps. After each step, tell me what was already in place, what you added, and what you suggest changing. When a step needs me, stop and ask. 1. Inventory - List every service in the repository: HTTP APIs, workers, scheduled jobs, and browser frontends. - For each service, find how it sends telemetry today: an OpenTelemetry SDK, the Superlog browser SDK, another vendor's agent or SDK, or nothing. Use the service name it already reports. Give new services a short, stable name. - Map how the services call each other: HTTP and gRPC calls, queues and topics, background jobs, and calls from the browser to the backend. - Read the workspace: list_integrations, list_services, list_ingest_keys, get_error_notifications, list_dashboards, list_alerts, and list_synthetic_checks. Query the last 24 hours of traces, logs, and metrics for each service in list_services to see which signals arrive. 2. Ingest keys - Skip services that already send to Superlog, and reuse the key a project already reads from its environment or secret manager. - For services that send nothing yet, create a key with create_ingest_key: one for the backend services and one for each browser app. Name each key after what uses it, and check list_ingest_keys first so you don't create a second key with the same name. - Add placeholders for new settings to the example environment file. Tell me where to set the real values, or set them in the secret manager the project already uses. 3. Backend services: OpenTelemetry - If a service already exports OpenTelemetry to Superlog, keep its setup and only fill gaps from the list below. - If it sends to another vendor, don't remove that. Ask me whether to add Superlog as a second exporter or to replace it. - For services with nothing: use the official OpenTelemetry SDK for the service's language, with automatic instrumentation for its framework, HTTP clients, database clients, and queues. Configure the exporters only with environment variables: OTEL_EXPORTER_OTLP_ENDPOINT= OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf OTEL_EXPORTER_OTLP_HEADERS=x-api-key= Send traces, metrics, and logs. Start the SDK before the app loads other modules. Flush and shut it down when the process exits. - Gaps to check on every service: - service.name, service.version, and deployment.environment.name are set. - The logger is connected to the OpenTelemetry logs SDK, so each record carries its trace and span IDs. Console output stays. - Unhandled exceptions are recorded on the active span as exception events and logged at error level, so Superlog groups them into error issues. - The few operations that matter most to users, such as checkout or sign-in, have spans. 4. Browser frontends: Superlog browser SDK - If @superlog/browser is already set up, keep it and only fill gaps. - Otherwise install @superlog/browser, and @superlog/react for React apps. Follow https://docs.superlog.sh/guides/browser. Call init before the app renders, with service, release, environment, the browser app's ingest key as ingestKey, and the endpoint from list_ingest_keys as endpoint. - Gaps to check: the React error boundary and router instrumentation for React apps, and source map uploads in the build with @superlog/sourcemaps and SUPERLOG_API_KEY, using the same release value as init. 5. Connect requests across services One user action must show up as one trace, from the browser through every service it reaches. Check each link and fix only the ones that break. - Use W3C trace context (traceparent and tracestate) everywhere. - Browser to backend: tracePropagationTargets in the browser SDK lists the app's API origins, and the API's CORS settings allow the traceparent and tracestate headers. - Service to service: every outgoing HTTP and gRPC client sends traceparent, every server continues it, and proxies, gateways, and load balancers pass the headers through. - Queues and background jobs: the trace context is injected into each message's headers or attributes when it is sent and extracted when it is processed, so the job's spans join the trace that enqueued it. Use the instrumentation library for the queue if there is one. - Request IDs: if the app has a request ID, it is on the active span as an attribute and on every log record, and the response returns the trace ID in a header so support can find a user's request. - Verify: after step 6, find a trace for a user action that crosses services with query_traces, open it with get_trace, and confirm it has spans from the browser and every service involved. 6. Verify the data - If you changed code, run the project's checks. Then ask me to deploy, or to run the services locally with the settings, and send some traffic. - Confirm each service with list_services, query_traces, query_logs, and query_metrics. Note the real metric names, routes, and attribute names. Build everything below from data you have seen, not from guesses. 7. Slack and error notifications - If Slack is not connected, call start_integration_connection for Slack and wait for me to approve it. Then call list_slack_channels. - If error notifications are already on, keep their channel. Otherwise ask me which channel to use and turn them on with update_error_notifications. - For new alerts and checks, use the channel the existing alerts post to. If there are none, ask me which channel to use. 8. Dashboards - Read each existing dashboard with get_dashboard. Treat a dashboard as covering a service if its name or its widgets are about that service. - If no dashboard covers the whole system, create a "Service health" dashboard: requests per service, error spans per service, p95 latency per service, a list of recent error logs, and a list of recent error traces, with a dashboard variable for deployment.environment.name. - For each service with no dashboard, create one: throughput, errors, and p50, p95, and p99 latency by route; the slowest routes as a table; database and outgoing call latency; runtime metrics such as memory and CPU if the service sends them; and a list of its error logs. - For dashboards that already exist, list the charts they are missing as suggestions. Don't add them without my approval. - Query each widget's data before you add it. Arrange new dashboards with update_dashboard_layout so the most important charts are at the top. 9. Alerts - Only alerts someone should act on. Each alert name says what is broken. Superlog alerts compare one value with a threshold. They cannot divide two values, so use counts and percentiles. - For each service, these are the cases to cover where they apply: a. Down: span count below 1 over 10 minutes, for services with steady traffic. b. Failing requests: error span count above a threshold. c. Slow: p95 span duration above a threshold on the main routes. d. Crashes: fatal logs above 0. e. Backlog: queue depth or job lag metrics above a threshold, if the service has them. - Read each existing alert with get_alert. A case is covered when an existing alert watches the same service and the same kind of failure, even with a different threshold or name. Skip covered cases. - For uncovered cases, set the threshold from the last 7 days of data so it does not fire on normal peaks. Check each new alert with preview_alert, show me the rule, threshold, and preview, and wait for my approval before create_alert. - If an existing alert looks too noisy or too quiet, suggest a change with its preview. Don't change it without my approval. 10. Synthetic checks - Skip URLs that already have a check. - For each public health endpoint and main page without one, create a check: every minute, retry once, alert after 2 failed runs. Assert a 2xx status and a response time, a JSON status field if the health endpoint returns one, and a TLS certificate that expires in more than 14 days. 11. Terraform - If the repository already manages Superlog or other infrastructure with Terraform, offer to add the output of export_terraform to it. Otherwise skip this step. Finish with a table of every service, ingest key, dashboard, alert, and synthetic check, marked as already in place, added, or suggested, and a list of anything you could not set up and why. ``` The agent keeps what is already set up and adds only what is missing, so you can run the prompt again at any time. It shows you each new alert before it creates it, and suggests changes to existing ones without making them. Review the thresholds. You know which numbers mean users are affected. ## Checklist Work through these steps for each service you run. Each one links to the page that covers it and has a prompt that sets up or improves only that part. You can run a prompt on its own, as often as you like. It keeps what exists and adds only what is missing. Each prompt needs the [Superlog MCP server](/assistants/claude). Alerts and dashboards are built from real data, so send telemetry first. **1. Send telemetry** Send logs, traces, and metrics from the service. Set `service.name` and `deployment.environment.name` so Superlog can group and filter by them. Connect logs to traces so each log record carries its trace and span IDs. See [Collect telemetry](/collect-telemetry/overview). > **Prompt: backend services** > > ```text theme={null} > Set up OpenTelemetry for the backend services in this repository so they send > traces, metrics, and logs to Superlog. You have the Superlog MCP server. Never > commit a key. > > This may already be partly or fully set up. Check what exists first. Keep what > works and add only what is missing. Never delete, rename, rotate, or replace > existing instrumentation or ingest keys. If you think one should change, list > the change and wait for my approval. Running this prompt again on a finished > setup should change nothing. > > 1. Inventory > - List every backend service: HTTP APIs, workers, and scheduled jobs. Find > how each one sends telemetry today: an OpenTelemetry SDK, another vendor's > agent or SDK, or nothing. Use the service name it already reports. Give > new services a short, stable name. > - Read list_services and list_ingest_keys. Query the last 24 hours of > traces, logs, and metrics for each service to see which signals arrive. > > 2. Ingest key > - Skip services that already send to Superlog, and reuse the key a project > already reads from its environment or secret manager. > - If services that send nothing still need a key, create one for the backend > services with create_ingest_key. Name it after what uses it, and check > list_ingest_keys first so you don't create a second key with the same name. > - Add placeholders for new settings to the example environment file. Tell > me where to set the real values, or set them in the secret manager the > project already uses. > > 3. Instrumentation > - If a service already exports OpenTelemetry to Superlog, keep its setup and > only fill gaps from the list below. > - If it sends to another vendor, don't remove that. Ask me whether to add > Superlog as a second exporter or to replace it. > - For services with nothing: use the official OpenTelemetry SDK for the > service's language, with automatic instrumentation for its framework, HTTP > clients, database clients, and queues. Configure the exporters only with > environment variables: > OTEL_EXPORTER_OTLP_ENDPOINT= > OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf > OTEL_EXPORTER_OTLP_HEADERS=x-api-key= > Send traces, metrics, and logs. Start the SDK before the app loads other > modules. Flush and shut it down when the process exits. > - Gaps to check on every service: > - service.name, service.version, and deployment.environment.name are set. > - The logger is connected to the OpenTelemetry logs SDK, so each record > carries its trace and span IDs. Console output stays. > - Unhandled exceptions are recorded on the active span as exception events > and logged at error level, so Superlog groups them into error issues. > - The few operations that matter most to users, such as checkout or > sign-in, have spans. > > 4. Verify > - If you changed code, run the project's checks. Then ask me to deploy, or > to run the services locally with the settings, and send some traffic. > - Confirm each service with list_services, query_traces, query_logs, and > query_metrics. > > Finish with a table of every service and ingest key, marked as already in > place, added, or suggested, and a list of anything you could not set up and why. > ``` > **Prompt: browser frontends** > > ```text theme={null} > Set up the Superlog browser SDK for the browser frontends in this repository. > You have the Superlog MCP server. A workspace API key for source map uploads may > be in SUPERLOG_API_KEY. Never commit a key. > > This may already be partly or fully set up. Check what exists first. Keep what > works and add only what is missing. Never delete, rename, rotate, or replace > existing instrumentation or ingest keys. If you think one should change, list > the change and wait for my approval. Running this prompt again on a finished > setup should change nothing. > > 1. Inventory > - List every browser frontend. Find how each one sends telemetry today: the > Superlog browser SDK, another vendor's SDK, or nothing. Use the service > name it already reports. Give new apps a short, stable name. > - Read list_services and list_ingest_keys. Query the last 24 hours of traces > and logs for each app to see which signals arrive. > > 2. Ingest key > - Skip apps that already send to Superlog, and reuse the key a project > already reads from its environment. > - If an app that sends nothing still needs a key, create one for it with > create_ingest_key. Name it after the app, and check list_ingest_keys first > so you don't create a second key with the same name. > - Add placeholders for new settings to the example environment file. Tell > me where to set the real values. > > 3. Instrumentation > - If @superlog/browser is already set up, keep it and only fill gaps. > - If an app sends to another vendor, don't remove that. Ask me whether to > add Superlog alongside it or to replace it. > - Otherwise install @superlog/browser, and @superlog/react for React apps. > Follow https://docs.superlog.sh/guides/browser. Call init before the app > renders, with service, release, environment, the app's ingest key as > ingestKey, and the endpoint from list_ingest_keys as endpoint. > - Gaps to check: the React error boundary and router instrumentation for > React apps, and source map uploads in the build with @superlog/sourcemaps > and SUPERLOG_API_KEY, using the same release value as init. If the > endpoint is on us.superlog.sh, set the upload url to > https://us.superlog.sh. > > 4. Verify > - If you changed code, run the project's checks. Then ask me to deploy, or > to run the app locally with the settings, and open it. > - Confirm each app with list_services, query_traces, and query_logs. > > Finish with a table of every app and ingest key, marked as already in place, > added, or suggested, and a list of anything you could not set up and why. > ``` **2. Connect requests across services** Pass W3C trace context (`traceparent`) on every call between services, including from the browser to your API and through queues and background jobs. Then one user action shows up as one trace. If your app has a request ID, add it to spans and logs. See [Traces](/telemetry/traces) and [Browser and React](/guides/browser). > **Prompt: connect requests across services** > > ```text theme={null} > Connect requests across the services in this repository so one user action shows > up as one trace in Superlog, from the browser through every service it reaches. > You have the Superlog MCP server. > > This may already be partly or fully set up. Check each link and fix only the > ones that break. Keep what works. Never remove existing instrumentation. If you > think something that works should change, list the change and wait for my > approval. Running this prompt again on a finished setup should change nothing. > > 1. Inventory > - Map how the services call each other: HTTP and gRPC calls, queues and > topics, background jobs, and calls from the browser to the backend. > - Read list_services. If a service sends no telemetry yet, list it and move > on. > > 2. Check each link > - Use W3C trace context (traceparent and tracestate) everywhere. > - Browser to backend: tracePropagationTargets in the browser SDK lists the > app's API origins, and the API's CORS settings allow the traceparent and > tracestate headers. > - Service to service: every outgoing HTTP and gRPC client sends > traceparent, every server continues it, and proxies, gateways, and load > balancers pass the headers through. > - Queues and background jobs: the trace context is injected into each > message's headers or attributes when it is sent and extracted when it is > processed, so the job's spans join the trace that enqueued it. Use the > instrumentation library for the queue if there is one. > - Request IDs: if the app has a request ID, it is on the active span as an > attribute and on every log record, and the response returns the trace ID > in a header so support can find a user's request. > > 3. Verify > - If you changed code, run the project's checks. Then ask me to deploy, or > to run the services locally, and send some traffic. > - Find a trace for a user action that crosses services with query_traces, > open it with get_trace, and confirm it has spans from the browser and > every service involved. > > Finish with a table of every link, marked as already working, fixed, or > suggested, and a list of anything you could not connect and why. > ``` **3. Connect Slack** Slack is where alerts, error notifications, and synthetic check failures go. See [Slack](/integrations/slack). > **Prompt: connect Slack** > > ```text theme={null} > Connect Slack to Superlog. You have the Superlog MCP server. > > Slack may already be connected. Keep an existing connection as it is. Running > this prompt again on a finished setup should change nothing. > > 1. Call list_integrations. If Slack is connected, skip to step 3. > 2. Call start_integration_connection for Slack and wait for me to approve it. > Then confirm the connection with list_integrations. > 3. Call list_slack_channels. If a channel I need is missing, call > refresh_integrations and list them again. For a private channel, ask me to > invite the Superlog app first. > > Finish by saying whether Slack was already connected or is newly connected, and > which channels Superlog can post to. > ``` **4. Turn on error notifications** Superlog groups exceptions into issues on its own. Turn on notifications so a Slack channel hears about each new error and each regression. Resolve or silence issues from the Slack message. See [Errors](/telemetry/errors#slack-notifications). > **Prompt: turn on error notifications** > > ```text theme={null} > Turn on Superlog error notifications, so a Slack channel hears about each new > error and each regression. You have the Superlog MCP server. This needs a > workspace owner or admin. If the tools refuse, tell me and stop. > > These may already be on. Keep the current channel. If you think it should > change, tell me and wait for my approval. Running this prompt again on a > finished setup should change nothing. > > 1. Call get_error_notifications. If notifications are on, skip to step 4. > 2. Call list_integrations. If Slack is not connected, call > start_integration_connection for Slack and wait for me to approve it. > 3. Call list_slack_channels and ask me which channel to use. For a private > channel, ask me to invite the Superlog app first. Then turn notifications on > with update_error_notifications. > 4. Confirm with get_error_notifications. > > Finish by saying whether notifications were already on or are newly on, and > which channel they post to. > ``` **5. Add alerts** Add an alert for each signal that means users are affected, such as a spike in error logs or slow requests on a key endpoint. Preview each alert before you save it. See [Alerts](/telemetry/alerts). > **Prompt: add alerts** > > ```text theme={null} > Add Superlog alerts for the failures in this workspace that someone should act > on. You have the Superlog MCP server. > > This may already be partly or fully set up. Check what exists first. Keep what > works and add only what is missing. Never delete, rename, or replace an existing > alert. If you think one should change, list the change and wait for my approval. > Running this prompt again on a finished setup should change nothing. > > 1. Read the workspace > - Call list_services, list_alerts, and list_integrations. Read each alert > with get_alert. > - Query traces, logs, and metrics for each service, and note the real metric > names, routes, and attribute names. Build alerts from data you have seen, > not from guesses. If a service sends no data, list it and move on. > > 2. Choose a channel > - Use the channel the existing alerts post to. If there are none, ask me > which channel to use. > - If Slack is not connected, call start_integration_connection for Slack and > wait for me to approve it. Take the channel from list_slack_channels. > > 3. Find what is missing > - Only alerts someone should act on. Each alert name says what is broken. > Superlog alerts compare one value with a threshold. They cannot divide two > values, so use counts and percentiles. > - For each service, these are the cases to cover where they apply: > a. Down: span count below 1 over 10 minutes, for services with steady > traffic. > b. Failing requests: error span count above a threshold. > c. Slow: p95 span duration above a threshold on the main routes. > d. Crashes: fatal logs above 0. > e. Backlog: queue depth or job lag metrics above a threshold, if the > service has them. > - A case is covered when an existing alert watches the same service and the > same kind of failure, even with a different threshold or name. Skip > covered cases. > > 4. Add alerts > - For uncovered cases, set the threshold from the last 7 days of data so it > does not fire on normal peaks. Check each new alert with preview_alert, > show me the rule, threshold, and preview, and wait for my approval before > create_alert. > - If an existing alert looks too noisy or too quiet, suggest a change with > its preview. Don't change it without my approval. > > Finish with a table of every service and case, marked as already in place, > added, or suggested, and a list of anything you could not set up and why. > ``` **6. Add synthetic checks** Add a check for each public endpoint and health route. Superlog requests it on a schedule and posts to Slack when it fails. See [Synthetic checks](/telemetry/synthetics). > **Prompt: add synthetic checks** > > ```text theme={null} > Add Superlog synthetic checks for the public endpoints of this application. You > have the Superlog MCP server. > > This may already be partly or fully set up. Check what exists first. Keep what > works and add only what is missing. Never delete, rename, or replace an existing > check. If you think one should change, list the change and wait for my approval. > Running this prompt again on a finished setup should change nothing. > > 1. Inventory > - Find each public health endpoint and main page in the repository. Ask me > for any public URL you can't tell from the code. > - Call list_synthetic_checks. Skip URLs that already have a check. > > 2. Choose a channel > - Use the channel the existing checks post to. If there are no checks, > use the channel from list_alerts. If there are no alerts either, ask > me which channel to use. > - If Slack is not connected, call start_integration_connection for Slack and > wait for me to approve it. Take the channel from list_slack_channels. > > 3. Add checks > - For each URL without a check, create one with create_synthetic_check: > every minute, retry once, alert after 2 failed runs. Assert a 2xx status > and a response time, a JSON status field if the health endpoint returns > one, and a TLS certificate that expires in more than 14 days. > - Confirm each new check has run with get_synthetic_check. If one fails, tell > me what it got. > > Finish with a table of every URL and check, marked as already in place, added, > or suggested, and a list of anything you could not set up and why. > ``` **7. Build a service dashboard** Chart request rate, errors, and latency for the service. Add a variable for the environment so one dashboard covers all of them. See [Dashboards](/telemetry/dashboards). > **Prompt: build dashboards** > > ```text theme={null} > Build Superlog dashboards for the services in this workspace. You have the > Superlog MCP server. > > This may already be partly or fully set up. Check what exists first. Keep what > works and add only what is missing. Never delete, rename, or replace an existing > dashboard or widget. If you think one should change, list the change and wait > for my approval. Running this prompt again on a finished setup should change > nothing. > > 1. Read the workspace > - Call list_services and list_dashboards. Read each dashboard with > get_dashboard. Treat a dashboard as covering a service if its name or its > widgets are about that service. > - Query traces, logs, and metrics for each service, and note the real metric > names, routes, and attribute names. Build charts from data you have seen, > not from guesses. If a service sends no data, list it and move on. > > 2. Add what is missing > - If no dashboard covers the whole system, create a "Service health" > dashboard: requests per service, error spans per service, p95 latency per > service, a list of recent error logs, and a list of recent error traces, > with a dashboard variable for deployment.environment.name. > - For each service with no dashboard, create one: throughput, errors, and > p50, p95, and p99 latency by route; the slowest routes as a table; > database and outgoing call latency; runtime metrics such as memory and > CPU if the service sends them; and a list of its error logs. > - For dashboards that already exist, list the charts they are missing as > suggestions. Don't add them without my approval. > - Query each widget's data before you add it. Arrange new dashboards with > update_dashboard_layout so the most important charts are at the top. > > Finish with a table of every dashboard with its link, marked as already in > place, added, or suggested, and a list of anything you could not set up and why. > ``` If you already manage infrastructure with Terraform, you can keep your alerts, dashboards, and synthetic checks there too. See [Terraform provider](/developer/terraform). > **Prompt: move Superlog into Terraform** > > ```text theme={null} > Keep this workspace's Superlog alerts, dashboards, and synthetic checks in this > repository's Terraform. You have the Superlog MCP server. A workspace API key > may be in SUPERLOG_API_KEY. Never commit a key. > > This may already be partly or fully set up. Check what exists first. Keep what > works and add only what is missing. Don't run apply without my approval. Running > this prompt again on a finished setup should change nothing. > > 1. Inventory > - If the repository doesn't use Terraform or OpenTofu, ask me whether to add > it before you continue. > - Find the superloglabs/superlog provider and every superlog_alert, > superlog_dashboard, and superlog_synthetic_check resource. > - Call list_alerts, list_dashboards, and list_synthetic_checks. Compare them > with the resources to find the objects Terraform doesn't manage yet. > > 2. Add what is missing > - If the provider is not configured, add it. Set endpoint to > https://superlog.sh, or https://us.superlog.sh if the endpoint from > list_ingest_keys is on us.superlog.sh. Read the key from SUPERLOG_API_KEY. > - Call export_terraform with the IDs of the unmanaged objects, and add the > output next to the existing configuration. Its import blocks adopt the > existing objects instead of creating copies. > - Tell me which sensitive variables to set for secret headers on synthetic > checks. > - Tell me that widgets added to a Terraform-managed dashboard in Superlog > are removed on the next apply. > > 3. Verify > - Run plan and show me the result. It should only import objects. If it > would change or destroy one, stop and explain why. > - Wait for my approval before you apply. > > Finish with a table of every alert, dashboard, and synthetic check, marked as > already managed, added, or suggested, and a list of anything you could not add > and why. > ``` # Security Source: https://docs.superlog.sh/security How Superlog protects credentials, isolates runs, and limits what agents can access. Superlog gives agents useful access to your tools without handing them your keys. This page summarizes the controls. For more detail, read the [security whitepaper](https://superlog.sh/security). ## Credentials stay outside the sandbox Agents run in sandboxes that do not hold your provider credentials. | Credential | How agents use it | | - | - | | GitHub | Superlog copies repositories into the sandbox and opens pull requests on the agent's behalf. The sandbox has no GitHub token. | | Integrations | Superlog calls Slack, Sentry, Datadog, Linear, and MCP servers for the agent through a broker outside the sandbox. | | Model API keys | Model requests go through a broker that holds the key. Keys never enter the sandbox. | | ChatGPT subscription | Each run gets a copy of the login with placeholder tokens. The real access token is substituted at the network boundary, only for requests to ChatGPT. | | Workspace secrets | The sandbox gets a placeholder. The real value is substituted at the network boundary, only for allowed hosts. | ## Encryption * Integration tokens and API keys are encrypted with AES-256-GCM before storage, with a fresh random nonce for each encryption. * Database storage and application logs use managed encryption keys with rotation enabled. * Public traffic and database connections require TLS. ## Short-lived cloud access * AWS uses temporary credentials from an IAM role in your account. An explicit deny blocks secrets, SSM parameters, and KMS decryption. * Google Cloud uses Workload Identity Federation. No service account key is created or stored. * The roles you create define the access boundary. ## Isolated runs * Every automation, integration, secret, run, and member belongs to one workspace. Queries and API routes enforce that ownership. * Each run gets its own sandbox. Sandboxes are never shared across workspaces. * Each run keeps the exact automation configuration it started with. ## Limited tools * Most built-in integrations expose only read-only tools. Write actions are limited to opening pull requests, posting to Slack, and creating Linear issues. * Datadog and custom MCP servers pass their tools through. Scope the credentials you give them. * Custom MCP servers must use HTTPS and resolve to public addresses. Authorization is never forwarded across origins. * Agents treat trigger events as untrusted input. ## Webhooks Slack, GitHub, Sentry, and Discord webhooks are verified against their signatures before Superlog acts on them. Retries are deduplicated. ## Report a vulnerability See [SECURITY.md](https://github.com/superloglabs/responder-oss/blob/main/SECURITY.md) for how to report a vulnerability privately. # Deploy Superlog Source: https://docs.superlog.sh/self-hosting/deployment Deploy the Superlog control plane and worker on your own infrastructure. You run two long-running services, the **control plane** and the **worker**, backed by one Postgres database. Both ship with Dockerfiles you can use as starting points. The application does not depend on a specific cloud provider. Both services need the same `DATABASE_URL`, `CREDENTIAL_ENCRYPTION_KEY`, and `INTERNAL_INGEST_TOKEN`. > [!WARNING] > > You are responsible for TLS termination, network isolation, database backups, secret injection, monitoring, scaling, and rollbacks. ## Deploy **1. Build the control plane** ```bash theme={null} docker build -f apps/control-plane/Dockerfile -t superlog-control-plane . ``` The Dockerfile is a generic building block. Adapt the networking, base image, and build arguments to your platform. **2. Serve the app and API from one origin** Serve the built assets in `apps/control-plane/dist` at your public origin, and route `/api/*` on the same origin to the control-plane service. Sign-in, OAuth callbacks, and webhooks all depend on one stable origin. ```text theme={null} https://superlog.example.com/ → static assets https://superlog.example.com/api/* → control-plane service ``` Set `BETTER_AUTH_URL` to this origin. Set `RESPONDER_PUBLIC_URL` too if integration callbacks and webhooks should use a different public origin. OAuth redirect URIs and webhook URLs are derived from it. **3. Run the worker** ```bash theme={null} docker build -f apps/worker/Dockerfile -t superlog-worker . ``` The worker serves no public traffic. It needs outbound access to the database, Daytona, model providers, and connected integrations. **4. Apply migrations** Before each release starts, apply every migration in `drizzle/`: ```bash theme={null} pnpm db:migrate ``` **5. Turn on automations** Set `RESPONDER_NEW_ORGANIZATION_CAPABILITIES=automations,simplified_navigation` on the control plane so new workspaces get the automations product. See [Self-hosting overview](/self-hosting/overview#turn-on-automations). > [!WARNING] > > Changing the public origin after integrations are connected breaks their OAuth callbacks and webhooks. Update the redirect and webhook URLs in each provider app if you change it. ## Required configuration | Variable | Service | Purpose | | - | - | - | | `DATABASE_URL` | Both | Postgres connection string. | | `CREDENTIAL_ENCRYPTION_KEY` | Both | Base64-encoded 32-byte key that encrypts stored credentials. Must match on both services. | | `INTERNAL_INGEST_TOKEN` | Both | Shared token for internal requests. Must match on both services. | | `DAYTONA_API_KEY` | Both | Sandboxes for runs, and the vault for workspace secrets. | | `BETTER_AUTH_SECRET` | Control plane | Signs sign-in sessions. | | `BETTER_AUTH_URL` | Control plane | Public origin of the app. | | `AI_GATEWAY_API_KEY` | Both | Included usage for automations. Optional if every workspace brings its own key or subscription. | | `OPENAI_API_KEY` | Worker | Tag mode. | Generate the encryption key and internal token with: ```bash theme={null} openssl rand -base64 32 # CREDENTIAL_ENCRYPTION_KEY openssl rand -hex 32 # INTERNAL_INGEST_TOKEN ``` See [Environment variables](/self-hosting/environment) for every option. ## After deployment Create provider apps for the integrations you want. Each integration page lists the required callback URLs, webhooks, and permissions. Integrations whose provider app is not configured show **Unavailable** in the app. # Environment variables Source: https://docs.superlog.sh/self-hosting/environment Environment variables for the Superlog control plane and worker: database, sign-in, sandboxes, models, integrations, and billing. The control plane and worker are configured through environment variables. Both services share a Postgres database and must use the same encryption key and internal token. Inject secrets through your platform's secret store. The repository's [`.env.example`](https://github.com/superloglabs/responder-oss/blob/main/.env.example) lists every option. *** ## Core / Required Set these before starting either service. The encryption key and internal token are shared across both services. > [!WARNING] > > `CREDENTIAL_ENCRYPTION_KEY` and `INTERNAL_INGEST_TOKEN` must be **identical** on both the control plane and the worker. If they differ, the worker cannot decrypt integration credentials and authenticated internal requests will fail. **DATABASE\_URL** `string` *required* PostgreSQL connection string for the shared application database. ```text theme={null} postgresql://user:pass@host:5432/responder ``` Both the control plane and the worker connect to this database. Use a connection pooler (e.g. PgBouncer) for high-traffic deployments and set `DATABASE_POOL_SIZE` to match your pooler's limits. **DATABASE\_POOL\_SIZE** `number` (default: 5) Optional. Maximum number of database connections per process. Defaults to `5`. Increase this value when using a connection pooler such as PgBouncer, and set it to match your pooler's per-client connection limit. **CREDENTIAL\_ENCRYPTION\_KEY** `string` *required* Base64-encoded 32-byte key used to encrypt all tenant integration credentials before they are stored in the database. Generate a secure value with: ```bash theme={null} openssl rand -base64 32 ``` Set the same value on **both** the control plane and the worker. Rotating this key requires re-encrypting all stored credentials. **INTERNAL\_INGEST\_TOKEN** `string` *required* Shared bearer token that the worker presents when making authenticated internal requests to the control plane. Generate a random value: ```bash theme={null} openssl rand -hex 32 ``` Set the same value on both services. **BETTER\_AUTH\_SECRET** `string` *required* Secret used by Better Auth to sign and verify session tokens. Use a long, random string. Changing this value invalidates all active sessions. **RESPONDER\_PUBLIC\_URL** `string` Optional. Stable public HTTPS origin for integration OAuth callbacks and webhooks, for example `https://superlog.example.com`. Defaults to `BETTER_AUTH_URL`. It must be reachable by external providers. **RESPONDER\_NEW\_ORGANIZATION\_CAPABILITIES** `string` Comma-separated capabilities that every new workspace starts with. Set to `automations,simplified_navigation` to give new workspaces the automations product described in these docs. Applies only to workspaces created after it is set. **CONTROL\_PLANE\_URL** `string` Public app URL used in links that the worker sends, such as Slack messages. **SUPERUSER\_EMAILS** `string` Optional. Comma-separated sign-in emails that get platform-wide support access. Leave empty unless you operate the deployment for other teams. *** ## Sandboxes and models Runs execute in Daytona sandboxes. Set `DAYTONA_API_KEY` for any run, and `AI_GATEWAY_API_KEY` for automations on included usage. **DAYTONA\_API\_KEY** `string` *required* API key for Daytona. Required to create run sandboxes and to store workspace secrets in Daytona's write-only vault. **AI\_GATEWAY\_API\_KEY** `string` Vercel AI Gateway key that funds automation runs on included usage. Workspaces with their own API key or ChatGPT subscription do not need it. Without it, automations need a workspace key or subscription. **OPENAI\_API\_KEY** `string` OpenAI API key the worker uses for tag mode. Workspace model keys in **Settings → Models** apply to automations only. **OPENAI\_AGENT\_MODEL** `string` (default: gpt-5.6-sol) Overrides the tag mode model. Defaults to `gpt-5.6-sol`. **DAYTONA\_API\_URL** `string` Optional. Override the Daytona API endpoint. Leave unset to use the Daytona default. **DAYTONA\_TARGET** `string` Optional. Specify a Daytona target environment. Leave unset to use the Daytona default. *** ## Authentication Sign-in uses Better Auth. Email and password sign-in is always available. Google and GitHub sign-in are optional. **BETTER\_AUTH\_URL** `string` *required* Public origin of the app, for example `https://superlog.example.com`. **AUTH\_GOOGLE\_CLIENT\_ID** `string` Google OAuth 2.0 client ID for Google login. Create an OAuth app in Google Cloud Console and set the authorized redirect URI to: ```text theme={null} https://superlog.example.com/api/auth/callback/google ``` **AUTH\_GOOGLE\_CLIENT\_SECRET** `string` Google OAuth 2.0 client secret paired with `AUTH_GOOGLE_CLIENT_ID`. **AUTH\_GITHUB\_CLIENT\_ID** `string` GitHub OAuth app client ID for GitHub login. Set the authorization callback URL to: ```text theme={null} https://superlog.example.com/api/auth/callback/github ``` **AUTH\_GITHUB\_CLIENT\_SECRET** `string` GitHub OAuth app client secret paired with `AUTH_GITHUB_CLIENT_ID`. *** ## Invitation email Invitation emails are sent through Resend. Without it, invitations are still created and their links can be copied from **Settings → Workspace**. **RESEND\_API\_KEY** `string` API key for [Resend](https://resend.com). When omitted, invitations are created but not emailed. **RESPONDER\_FROM\_EMAIL** `string` (default: Responder \<[no-reply@superlog.sh](mailto:no-reply@superlog.sh)>) Sender address and display name for outgoing invitation emails. Use a domain you control and have verified with Resend. **RESPONDER\_REPLY\_TO\_EMAIL** `string` Optional. Reply-to address added to outgoing invitation emails. When set, replies from recipients are delivered to this address instead of the sender address. Leave unset to omit a reply-to header. *** ## Integrations (First-Party Apps) These integrations need an app registered with the provider. Callback and webhook URLs use your public origin. Dash0, PostHog, Grafana, Axiom, ClickStack, Langfuse, Upstash, Supabase, Datadog, and custom MCP servers need no deployment-level configuration. ### GitHub Create a public GitHub App and configure it as described in the integrations guide. The private key value should be the full PEM string (newlines escaped as `\n` or using a multi-line secret). | Variable | Description | | - | - | | `GITHUB_APP_ID` | Numeric GitHub App ID shown on the app's settings page | | `GITHUB_APP_SLUG` | URL slug of the GitHub App | | `GITHUB_APP_PRIVATE_KEY` | PEM-encoded private key for the GitHub App | | `GITHUB_CLIENT_ID` | OAuth client ID (for user authorization during installation) | | `GITHUB_CLIENT_SECRET` | OAuth client secret paired with `GITHUB_CLIENT_ID` | | `GITHUB_WEBHOOK_SECRET` | Secret used to verify `X-Hub-Signature-256` on incoming webhooks | OAuth callback: `{RESPONDER_PUBLIC_URL}/api/integrations/github/callback`\ Webhook URL: `{RESPONDER_PUBLIC_URL}/api/webhooks/github` ### Slack Configure a distributed Slack app with bot and user scopes as described in the integrations guide. | Variable | Description | | - | - | | `SLACK_CLIENT_ID` | Slack app client ID | | `SLACK_CLIENT_SECRET` | Slack app client secret | | `SLACK_SIGNING_SECRET` | Signing secret used to verify incoming Slack event payloads | OAuth callback: `{RESPONDER_PUBLIC_URL}/api/integrations/slack/callback`\ Events URL: `{RESPONDER_PUBLIC_URL}/api/webhooks/slack`\ Interactivity URL: `{RESPONDER_PUBLIC_URL}/api/webhooks/slack/actions` ### Sentry Create a public Sentry integration with `issue.created` and `issue.unresolved` subscriptions. | Variable | Description | | - | - | | `SENTRY_APP_SLUG` | Sentry integration slug | | `SENTRY_CLIENT_ID` | Sentry integration client ID | | `SENTRY_CLIENT_SECRET` | Sentry integration client secret | Redirect URL: `{RESPONDER_PUBLIC_URL}/api/integrations/sentry/callback`\ Webhook URL: `{RESPONDER_PUBLIC_URL}/api/webhooks/sentry` ### Linear Create a Linear OAuth app with `read` and `write` scopes. | Variable | Description | | - | - | | `LINEAR_CLIENT_ID` | Linear OAuth app client ID | | `LINEAR_CLIENT_SECRET` | Linear OAuth app client secret | OAuth callback: `{RESPONDER_PUBLIC_URL}/api/integrations/linear/callback` ### Vercel Create a Vercel Integration with read-only scopes (no write, no secret/token access). | Variable | Description | | - | - | | `VERCEL_INTEGRATION_SLUG` | Slug of your Vercel Integration | | `VERCEL_CLIENT_ID` | Vercel integration client ID | | `VERCEL_CLIENT_SECRET` | Vercel integration client secret | Redirect URL: `{RESPONDER_PUBLIC_URL}/api/integrations/vercel/callback` ### Discord Create a Discord application with a bot, enable **Requires OAuth2 Code Grant**, and grant View Channels permission. | Variable | Description | | - | - | | `DISCORD_APPLICATION_ID` | Discord application ID | | `DISCORD_BOT_TOKEN` | Bot token for the Discord application | | `DISCORD_CLIENT_SECRET` | OAuth2 client secret | | `DISCORD_PUBLIC_KEY` | Public key for verifying interaction signatures | OAuth callback: `{RESPONDER_PUBLIC_URL}/api/integrations/discord/callback`\ Interactions endpoint: `{RESPONDER_PUBLIC_URL}/api/webhooks/discord` *** ## AWS Integration AWS support requires a stable broker IAM role that Superlog assumes to access customer AWS accounts. The CloudFormation template variables are optional but recommended for production — they let Superlog generate a short-lived presigned S3 URL instead of offering a file download. **AWS\_INTEGRATION\_PRINCIPAL\_ARN** `string` ARN of the stable broker IAM role that Superlog assumes in order to call `sts:AssumeRole` on customer `ResponderInvestigationRole` roles. Required for AWS context to work on self-hosted deployments. The broker must allow `sts:AssumeRole` only on roles named `ResponderInvestigationRole`. ```text theme={null} arn:aws:iam::123456789012:role/ResponderBrokerRole ``` **AWS\_INTEGRATION\_TEMPLATE\_BUCKET** `string` Name of the private S3 bucket that hosts the CloudFormation stack template. When all three `AWS_INTEGRATION_TEMPLATE_*` values are set, Superlog generates a presigned URL for CloudFormation Quick Create instead of offering a file download. **AWS\_INTEGRATION\_TEMPLATE\_KEY** `string` S3 object key of the CloudFormation template within `AWS_INTEGRATION_TEMPLATE_BUCKET`. **AWS\_INTEGRATION\_TEMPLATE\_REGION** `string` AWS region of `AWS_INTEGRATION_TEMPLATE_BUCKET`, used to construct the presigned URL. *** ## Google Cloud Integration Google Cloud setup uses a one-time OAuth flow to provision customer-owned Workload Identity Federation resources. Superlog does not store a long-lived token — the setup token is used and revoked during the background setup job. **GCP\_OAUTH\_CLIENT\_ID** `string` Client ID of the Google OAuth web client used during Google Cloud project setup. The Google Cloud project that owns this client must have the Cloud Resource Manager, Service Usage, and IAM APIs enabled. **GCP\_OAUTH\_CLIENT\_SECRET** `string` Client secret paired with `GCP_OAUTH_CLIENT_ID`. > [!NOTE] > > The Google Cloud integration also requires `AWS_INTEGRATION_PRINCIPAL_ARN`. Superlog uses the same AWS broker role to federate a short-lived Google Cloud identity via Workload Identity Federation. Self-hosted deployments must run on AWS with permission to assume that role. OAuth callback: `{RESPONDER_PUBLIC_URL}/api/integrations/gcp/callback` *** ## Billing (Optional) Billing meters each workspace's monthly usage allowance through [Autumn](https://useautumn.com). Without it, usage is not metered or limited. **BILLING\_ENABLED** `string` (default: false) Set to `true` to meter usage. Automations and tag mode draw on each workspace's monthly allowance. Configure it on both services. **AUTUMN\_SECRET\_KEY** `string` Secret key for the [Autumn](https://useautumn.com) billing service. Required when `BILLING_ENABLED=true`. Configure this on both the control plane and the worker. *** ## Monitoring and analytics (optional) | Variable | Purpose | | - | - | | `SENTRY_DSN`, `VITE_SENTRY_DSN` | Error monitoring for the services and the browser app. | | `SENTRY_ENVIRONMENT`, `SENTRY_RELEASE`, `SENTRY_TRACES_SAMPLE_RATE` | Server error monitoring settings. `VITE_`-prefixed versions apply to the browser. | | `SENTRY_ORG`, `SENTRY_PROJECT`, `SENTRY_AUTH_TOKEN` | Build-time source map upload. Never expose the auth token through a `VITE_` variable. | | `POSTHOG_PROJECT_TOKEN`, `POSTHOG_HOST` | Product analytics from the services. `VITE_`-prefixed versions apply to the browser. | # Run Superlog locally Source: https://docs.superlog.sh/self-hosting/local-development Run the full Superlog stack on your machine with Docker and pnpm. The local setup runs Postgres, the control plane, and the worker behind a local HTTPS address. ## Prerequisites * **Node.js 24 or newer** * **pnpm 11** * **Docker** ## Start the stack **1. Clone and set up** ```bash theme={null} git clone https://github.com/superloglabs/responder-oss.git cd responder-oss pnpm local:setup ``` `local:setup` installs dependencies, generates a gitignored `.env.local`, starts Postgres, applies the migrations, and creates a local example runtime profile. Run it once. **2. Configure .env.local** Open `.env.local` and set: ```bash theme={null} # Give new workspaces the automations product RESPONDER_NEW_ORGANIZATION_CAPABILITIES=automations,simplified_navigation # Sandboxes for runs, and the vault for workspace secrets DAYTONA_API_KEY= # Included usage for automations through Vercel AI Gateway AI_GATEWAY_API_KEY= # Tag mode OPENAI_API_KEY= ``` Without `AI_GATEWAY_API_KEY`, automations still run when the workspace adds its own API key or ChatGPT subscription in **Settings → Models**. **3. Start the stack** ```bash theme={null} pnpm local:dev ``` The command prints the local HTTPS address. Restart the stack after changing `.env.local`. **4. Create an account and workspace** Open the printed address, sign up, and create a workspace. It opens on **Automations**. See [Automations](/automations/overview). The app and sign-in work without provider credentials. Integration OAuth flows and webhooks need a public HTTPS address. Set `RESPONDER_NGROK_URL` to a static ngrok domain and `local:dev` starts a tunnel to it. Run `pnpm tunnel:claim` to route the tunnel to the current checkout. ## Seed demo data After you create a local account, you can add a demo workspace: ```bash theme={null} pnpm --filter @responder/core exec node scripts/local-seed-demo.mjs you@example.com ``` ## Stop the stack ```bash theme={null} pnpm local:down ``` The database is kept in a Docker volume for the next `pnpm local:dev`. ## Validate changes Run the full suite before opening a pull request: ```bash theme={null} pnpm typecheck pnpm lint pnpm test pnpm build ``` See [CONTRIBUTING.md](https://github.com/superloglabs/responder-oss/blob/main/CONTRIBUTING.md). # Self-hosting Superlog Source: https://docs.superlog.sh/self-hosting/overview Run the open-source Superlog application on your own infrastructure. Superlog's application is open source under the Apache License 2.0. The repository is [superloglabs/responder-oss](https://github.com/superloglabs/responder-oss), where the project is named Responder. It contains the web app, API, worker, shared domain code, and database migrations. The hosted service at [superlog.sh](https://superlog.sh) runs the same code. ## Architecture Superlog runs as two long-running Node.js services that share one Postgres database. ```text theme={null} Browser / providers │ HTTPS ▼ control plane (web app + API) │ ├── authentication and workspace configuration ├── encrypted integration credentials └── durable jobs ─────────────┐ ▼ worker ┌────────┼────────┐ ▼ ▼ ▼ sandbox model providers ``` * **Control plane.** Serves the React app and the API. Handles sign-in, workspaces, integration setup, webhooks, and job scheduling. * **Worker.** Claims jobs from Postgres, starts sandboxes, runs agents, and stores transcripts and results. It needs no inbound traffic. * **Sandboxes.** Runs execute in [Daytona](https://daytona.io) sandboxes. Workspace secrets are stored in Daytona's write-only vault. ## Turn on automations New workspaces get the automations product only when the deployment enables it. Set this on the control plane: ```bash theme={null} RESPONDER_NEW_ORGANIZATION_CAPABILITIES=automations,simplified_navigation ``` This applies to workspaces created after you set it. With it, new workspaces open on **Automations** and the sidebar matches these docs: **Automations**, **Integrations**, **Tag mode**, and **Settings**. Automations that use included usage, rather than a workspace's own API key or ChatGPT subscription, run through Vercel AI Gateway. Set `AI_GATEWAY_API_KEY` to enable them. ## Next steps > **[Local development](/self-hosting/local-development)** > > Run the full stack on your machine. > **[Deployment](/self-hosting/deployment)** > > Deploy the control plane and worker. > **[Environment variables](/self-hosting/environment)** > > Configure the database, sandboxes, models, and integrations. > **[Integrations](/integrations/overview)** > > Each integration page lists the provider app settings for self-hosted deployments. # API keys Source: https://docs.superlog.sh/settings/api-keys Create keys for the management API and the MCP server. API keys give the [management API](/api-reference/introduction) and the [MCP server](/api-reference/mcp) access to one workspace. With a key, they can read and change automations, runs, tag mode, model access, and workspace secrets. ## How keys work * A key acts as the member who created it. Changes made with it are recorded under that member's name. * A key stops working when it is revoked or when its member leaves the workspace. * Superlog stores only a hash of the key. You can see the full key once, right after you create it. ## Create a key **1. Open API keys** Go to **Settings → API keys**. **2. Name the key** Under **Create an API key**, enter a name that says where the key is used, such as `Claude Code` or `CI`, and click **Create key**. **3. Copy the key** Click **Copy key** and store it in your secret manager or MCP client. Keys start with `slk_`. ## Revoke a key Click **Revoke** next to the key. Anything that uses it stops working immediately. Members can revoke the keys they created. Admins and owners can revoke any key in the workspace. The **API keys** list shows the first characters of each key, the member it acts as, and when it was last used. # Plans and billing Source: https://docs.superlog.sh/settings/billing Superlog plans, what counts toward your usage quota, and what happens when you reach it. Superlog plans differ by usage quota. Start free and move up as your automations grow. See current prices on the [pricing page](https://superlog.sh/pricing). | Plan | Price | For | | - | - | - | | **Free** | \$0 / month | Teams getting started. A light usage quota, no card required. | | **Pro** | \$100 / month | Teams running automations daily. | | **Max** | \$200 / month | Teams with the highest demand. | | **Enterprise** | Custom | Organizations that need a custom quota, terms, and support. [Talk to us](https://cal.com/superlog/yc). | ## What counts toward your quota Two things: * **AI inference** that runs on Superlog's included usage. Runs that use your own API key or ChatGPT subscription are billed by your provider and do not count here. * **Sandbox compute**, the time each run's sandbox is running. This counts for every run, including runs on your own key. Automation runs and tag mode questions both draw on the quota. ## Check your usage Go to **Settings → Billing**. The **Included usage this month** card shows how much of the quota you have used, split into AI inference and sandbox compute, and when it resets. ## When you reach your quota A banner appears in the app and Superlog sends a notice to Slack. Work that is already running finishes. New runs and tag mode questions do not start until the quota resets at the start of the next billing period or you upgrade. ## Change plans In **Settings → Billing**, choose a plan: * **Upgrades** take effect immediately. Superlog charges the saved card for the prorated difference after you confirm. * **Downgrades** and returning to Free take effect at the end of the current billing period. Click **Manage billing** to update your payment method or see invoices. # Workspace and members Source: https://docs.superlog.sh/settings/workspace Invite teammates, manage roles, and switch between workspaces. A workspace holds your automations, integrations, secrets, runs, and members. Data and credentials are never shared across workspaces. You can belong to several workspaces and switch between them from the account menu at the top of the sidebar. Open **Settings** in the sidebar to manage the workspace. The tabs are **Workspace**, **Models**, and **Billing**. ## Roles | Role | Can do | | - | - | | **Admin** | Everything a member can do, plus invite people, change roles, and remove members. | | **Member** | Create and edit automations, connect integrations, configure tag mode, and view runs. | The person who creates a workspace is its first admin. ## Invite a teammate **1. Open the Workspace tab** Go to **Settings → Workspace**. **2. Send the invitation** Under **Invite a teammate**, enter their email, choose **Member** or **Admin**, and click **Invite**. **3. Share the link if needed** Superlog emails the invitation. Click **Copy link** to share it another way. Pending invitations are listed under **Pending invitations** with their expiry date. Admins can copy the link again or cancel the invitation. ## Manage members The **Members** list shows everyone in the workspace. Admins can change a member's role or click **Remove** to take them out of the workspace. # Workspace secrets Source: https://docs.superlog.sh/settings/workspace-secrets Let agents call your APIs with credentials they never see. Workspace secrets let an agent call an API that needs a credential, such as an internal service or a provider without a built-in integration, without exposing the credential to the agent. ## How secrets work 1. You store a secret with a name, a value, and a list of allowed hosts. 2. When a run uses the secret, the sandbox gets an environment variable with the secret's name. Its value is a placeholder, not the real credential. 3. When the agent sends a request to an allowed host, Superlog replaces the placeholder with the real value at the network boundary. Requests to other hosts keep the placeholder. The real value is never readable in the sandbox, in the transcript, or in the app after you store it. Superlog also blocks placeholders from appearing in pull requests, commit messages, and reports. ## Create a secret **1. Open the secret dialog** Open `/agents/new` in Superlog. In the **Workspace secrets** panel, click **Add secret**. **2. Name it** Under **Environment variable**, enter the name, for example `METRICS_API_KEY`. Names use uppercase letters, digits, and underscores, up to 80 characters. Some names, such as `PATH` and `HOME`, are reserved. **3. Enter the value** Paste the credential under **Secret value**. Values can be up to 64 KB. You cannot view the value again after you store it. **4. Set the allowed hosts** Under **Allowed hosts**, list 1 to 20 hostnames, without a scheme, path, or port. A leading `*.` matches subdomains. ```text theme={null} api.example.com, *.example.net ``` **5. Store it** Click **Store and add**. The secret is now available to every automation in the workspace and to tag mode. > [!WARNING] > > Allowed hosts are the boundary for the secret. List only the hosts the agent needs to call. ## Use a secret * **Automations:** In the automation editor, click **Add connector** and pick the secret under **Workspace secrets**. An automation can use up to 20 secrets. * **Tag mode:** In **Tag mode**, click **Choose secrets** under **Workspace secrets**. Tell the agent in its instructions which variable to use and for what, for example: "Call `https://api.example.com/v1/status` with the bearer token in `$METRICS_API_KEY`." ## Rotate a secret Secrets cannot be edited. To rotate a credential, create a new secret with a new name, select it in your automations and tag mode, and remove the old one from them. # Tag mode Source: https://docs.superlog.sh/tag-mode Mention Superlog in Slack to ask questions about your code, logs, and infrastructure, and get an answer in the thread. Tag mode lets anyone in your Slack workspace mention Superlog and get an answer in the thread. Use it for questions like "why is checkout slow since this morning?" or "did yesterday's deploy change how retries work?". Superlog looks at your connected integrations and repositories and replies with what it found, the evidence, and a suggested next step. Tag mode is read-only. It does not open pull requests, create tickets, or change anything in your tools. For work that should act, use an [automation](/automations/overview). ## Turn on tag mode **1. Connect Slack** Tag mode needs a Slack connection. Add Slack from **Integrations** if it is not connected. **2. Open tag mode** Click **Tag mode** in the sidebar and turn on **Slack tag mode**. **3. Choose what it can see** Under **Connected integrations**, turn each integration on or off. For GitHub, click configure and select the repositories it may read. For Vercel, select the projects. Use **Add integration** to connect more tools. **4. Add secrets (optional)** Under **Workspace secrets**, click **Choose secrets** to let tag mode call your own APIs. See [Workspace secrets](/settings/workspace-secrets). **5. Adjust the prompt (optional)** Under **Prompt**, edit the instructions tag mode follows for every question. Changes save automatically. ## Ask a question Mention the Superlog app in a channel it can read and write your question in the same message. Superlog adds an 👀 reaction, posts an "Investigating…" card in the thread, and then replies with its answer. Mention Superlog again in the same thread to ask a follow-up. It continues the same conversation with the context it already gathered for up to 24 hours. ## What tag mode can use Tag mode can read from every integration you turn on for it: | Category | Integrations | | - | - | | Code and deployment | GitHub (read-only), Vercel | | Observability | Sentry, Datadog, Dash0, PostHog, Grafana, Axiom, ClickStack, Langfuse | | Cloud and data | AWS, Google Cloud, Upstash, Supabase, custom MCP servers | | Workflow | Linear (read-only) | Tag mode can also edit code and run commands inside its sandbox to test an idea. Nothing in the sandbox is published. ## Tag mode and automations Slack automations with an **App mentioned** trigger run alongside tag mode. If you want a mention to do something specific, such as fix a bug and open a pull request, create an automation for it. See [Triggers](/automations/triggers#slack). Tag mode questions use your plan's usage allowance. See [Billing](/settings/billing). # Alerts Source: https://docs.superlog.sh/telemetry/alerts Get a Slack message when a log count, span measure, or metric crosses a threshold, and a reply when it recovers. > [!NOTE] > > Telemetry is in early access. To turn it on for your workspace, [book a call](https://cal.com/superlog/yc) or ask in [Discord](https://discord.gg/wJ56aRh8hx). An alert checks one value from your telemetry on a schedule and compares it with a threshold. When the value crosses the threshold, the alert fires and posts to Slack. When it comes back, the alert recovers and replies in the same thread. Open **Alerts**, under **Detect** in the sidebar, and click **New alert**. ## Create an alert The editor has three steps. Give the alert a name first. ### 1. Explore your data Pick a **Data source**: | Source | What it reads | | - | - | | **Logs** | Log records. Filter by **Severity** (**Fatal**, **Error**, **Warn**, **Info**). Severity matches exactly, so **Error** doesn't include **Fatal**. | | **Spans** | Spans from your traces. **Only spans with an error status** is on by default. | | **Metric** | One metric, as its **Average** or **Sum**. | Narrow the data with **Service** and attribute filters. A filter compares an attribute with a value using **is**, **is not**, or **does not contain**. All filters must match. Pick a **Preview time range** and click **Run search** to chart the matching data. ### 2. Set the threshold * **Trigger when value is**: **Above** or **Below**. * **Threshold**: a number. It is in milliseconds for span duration and in USD for AI cost. * **Over the last**: how much data each check reads, from 1 minute to 1 day. * **Check**: how often the alert runs, from **Every minute** to **Every hour**. The **Threshold preview** draws the threshold as a dashed line over your data. **Advanced settings** has two more options: * **Measure**: for logs and spans, **Count** or an aggregation of a field: **Distinct values**, **Sum**, **Average**, **Minimum**, **Maximum**, **Median**, or the **90th**, **95th**, or **99th percentile**. Then pick the **Field**. For spans, fields include **Duration**, AI usage such as cost and tokens, and span attributes. * **Group by**: split the value by service or an attribute. Turn on **Alert for each group** to have each group fire and recover on its own. Otherwise the groups are added up. ### 3. Where to notify Choose a **Slack channel**. Private channels appear once the Superlog app is in them. Without a channel, the alert still records its activations. Click **Create alert**. ## When an alert fires An activation starts when a check finds the value past the threshold. Superlog posts one message to the channel with the alert name, the value, the condition, a chart, and a **View alert** link. It doesn't post again while the activation lasts. The activation ends when a check finds the value back on the other side of the threshold. Superlog replies in the thread with how long it fired and the current value. Counts, distinct counts, and sums read zero when no data matches. Averages, extremes, percentiles, and metrics have no value then, so an open activation stays open until data arrives. Editing what an alert reads, or its threshold, ends open activations without a recovery message. The next check opens new ones if the value is still past the threshold. ## Alert status | Status | Meaning | | - | - | | **OK** | The last check found the value within the threshold. | | **Firing** | The value is past the threshold. Grouped alerts show how many groups are firing. | | **Check failed** | The last check or Slack post failed. The alert page shows why. | | **Not checked yet** | The alert has not run yet. | | **Off** | The alert is paused. | ## Alert page Click an alert to see its **Current evaluation**, recent evaluations, and **Activation history**. Click an activation to see the rule at the time, a timeline, and whether its Slack messages were delivered. **Pause alert** stops checks until you click **Resume alert**. **Edit alert** opens the editor, where you can also delete the alert. **Copy as Terraform** copies it for the [Terraform provider](/developer/terraform). ## Start automations from alerts Alert messages start automations that watch the alert's Slack channel with **New message in channel** or **Message posted or app mentioned**. Each automation runs once per activation and replies in the alert's thread. See [Triggers](/automations/triggers#slack). ## Manage alerts from an agent The [MCP server](/api-reference/mcp) and [REST API](/api-reference/introduction) offer `preview_alert`, `create_alert`, `update_alert`, `get_alert`, `list_alerts`, and `delete_alert`. `preview_alert` returns a draft rule's current value without saving it. `list_slack_channels` returns the channel and integration IDs. # Dashboards Source: https://docs.superlog.sh/telemetry/dashboards Chart logs, spans, and metrics on a shared grid, filter it with variables, and export it to Terraform. > [!NOTE] > > Telemetry is in early access. To turn it on for your workspace, [book a call](https://cal.com/superlog/yc) or ask in [Discord](https://discord.gg/wJ56aRh8hx). **Explore → Dashboards** lists the workspace's dashboards with their widget count and when they last changed. Every member of the workspace sees the same dashboards. Click **New dashboard**, enter a name, and click **Create dashboard**. ## Widgets Click **Add widget**. The editor shows a live preview as you change settings. Choose one of three kinds: | Kind | Reads | Shows | | - | - | - | | **Chart** | **Logs**, **Spans**, or a **Metric** | A value over time, a single number, bars, or a table. | | **List** | **Logs** or **Traces** | The most recent matching records. | | **Note** | | Markdown text: headings, lists, links, bold, and code. | ### Chart settings * **Measure** (logs and spans): **Count**, **Distinct values**, **Sum**, **Average**, **Minimum**, **Maximum**, **Median**, or the 90th, 95th, or 99th percentile. Anything other than a count reads a **Field**: an attribute, or for spans the **Duration** or an AI usage field such as **Cost** or **Input tokens**. * **Metric** and **Aggregation** (metrics): pick a metric, then keep **Default for the metric** or choose an aggregation. See [Metrics](/telemetry/metrics#aggregation). * **Display**: **Over time**, **Number**, **Bars**, or **Table**. * **Group by**: **Service**, an attribute, or for spans **AI model** or **AI provider**. Set how many **Series** or **Rows** to keep, up to 50. * **Filters**: an attribute, a comparison (**is**, **is not**, **does not contain**), and a value. Up to 50 per widget. * **Unit**: **Number**, **Milliseconds**, **Seconds**, **Bytes**, **Percent**, or **US dollars**. * Over time: **Bars** or **Lines**, and a **Legend** placed **Below** or **Beside**. * Number, bars, and table: **Compare with the previous period**. **Title** is optional. Without one, the widget is named from its settings. ### List settings Set **Rows** up to 500 for logs or 200 for traces, and add filters. Click a trace, or a log that has a trace ID, to open the trace. ## Layout Widgets sit on a 12-column grid. Drag a widget by its header to move it, and drag its corner to resize it. Changes save on their own. On narrow screens widgets stack in one column. Use the pencil icon to edit a widget and the trash icon to remove it. ## Time range The time picker works as in [Logs](/telemetry/logs#time-range). A range that ends now reloads every widget on its own while the page is open. Drag across a chart to zoom into that window, and use **Zoom out** to go back. ## Variables Variables add dropdowns above the widgets, such as an environment or service picker. Open the **⋯** menu and click **Add variable** (or **Variables** once there are some). | Setting | Meaning | | - | - | | **Name** | Letters, digits, and underscores, starting with a letter. Widgets refer to it as `$name`. | | **Label** | The text shown on the dropdown. | | **Attribute** | The attribute the variable filters, such as `deployment.environment`. The dropdown lists its values seen in the time range, with counts. | | **Options** | Fixed choices, separated by commas. | | **Allow several values** | Lets you pick more than one value. | | **Default** | The value selected when the dashboard opens. With options, it must be one of them. | To use a variable in a widget, add a filter with the value `$name` or `${name}`, or click **Filter by \$name** in the widget editor. When nothing is selected, the filter matches every value. A variable with no options, no attribute, and one value is a text field. ## Share a dashboard The page URL holds the time range and the selected variable values, so a link opens the same view for anyone in the workspace. ## Export to Terraform Open the **⋯** menu and click **Copy as Terraform**. Superlog copies configuration for the `superloglabs/superlog` Terraform provider, with an import block so applying it adopts the existing dashboard instead of creating a copy. To export from a script, call `GET /terraform` on the [management API](/api-reference/introduction) or the `export_terraform` MCP tool. Without IDs it exports every alert, dashboard, and synthetic check. Pass `dashboardIds` to export only those. ## Manage dashboards from an agent The [MCP server](/api-reference/mcp) can list, create, change, and delete dashboards and widgets. ## Rename or delete a dashboard Open the **⋯** menu and click **Rename** or **Delete dashboard**. Deleting a dashboard removes it and its widgets for everyone in the workspace. # Errors Source: https://docs.superlog.sh/telemetry/errors Group exceptions into issues, resolve or ignore them, and get a Slack message when a new error appears or a resolved one returns. > [!NOTE] > > Telemetry is in early access. To turn it on for your workspace, [book a call](https://cal.com/superlog/yc) or ask in [Discord](https://discord.gg/wJ56aRh8hx). **Errors**, under **Detect** in the sidebar, groups the exceptions your services send into issues. Each issue is one distinct problem. New exceptions show up within about a minute. ## What counts as an error Superlog reads two kinds of telemetry: * Span events named `exception`, as OpenTelemetry SDKs record them. * Logs at `ERROR` severity or above. You don't need to configure anything beyond sending telemetry. See [Instrument your app](/guides/instrument-your-app). ## How errors are grouped Each exception gets a fingerprint. Exceptions with the same fingerprint are one issue. * **With a stack trace:** the exception type and the top five frames from your own code. A frame is its function and file, without line numbers or bundle hashes, so the same bug groups across builds and hosts. * **Without your own frames:** the exception type and message. IDs, URLs, numbers, and timestamps in the message are replaced first, so per-request values don't split the issue. * **Logs without a stack:** the service, severity, and normalized log body. Frames from `node_modules`, language internals, browser extensions, and public CDNs are skipped. Chunk load errors and React hydration errors each group into one issue. ## The errors list Each row shows the issue title, its state, event count, a trend, and when it was last seen. | State | Meaning | | - | - | | **New** | First seen in the last 24 hours. | | **Recurring** | First seen more than 24 hours ago. | | **Regressed** | Resolved, then seen again. | Search by message or ID, and pick a **Time range**. Add filters for **Status**, **Activity** (**Still happening** means seen in the last 15 minutes), **Service**, or **Environment**. Sort by last seen, first seen, or events. Select issues to **Resolve**, **Ignore**, or **Reopen** them together. ## Issue status | Status | What happens to new occurrences | | - | - | | **Unresolved** | They are counted. | | **Resolved** | The issue reopens as regressed and notifies again. | | **Ignored** | They are counted. Nothing reopens or notifies. | An occurrence from before you resolved an issue does not reopen it. ## Issue detail Click an issue to open it. The page shows: * The **Latest event**, with its message, **Stack trace**, and attributes. Click **View trace** to open its [trace](/telemetry/traces). * **Occurrences** over the last 30 days. * **Related traces**: error traces from the same service and environment. * **Grouped by**: the fingerprint and the frames it was built from. Use **Ignore**, **Resolve**, or **Reopen** at the top of the page. ## Source maps for browser errors Once your build uploads its source maps, minified browser stacks are mapped back to your original files and functions before grouping. The browser's original stack stays on the event as `exception.stacktrace.minified`. Upload maps with the `@superlog/sourcemaps` package and a workspace API key. See [Browser](/guides/browser). ## Slack notifications Workspace owners and admins can post errors to one Slack channel. **1. Open notifications** On **Errors**, click **Notifications**. **2. Pick a channel** Turn on **Enable error notifications** and choose a **Slack channel**. For a private channel, invite the Superlog app first. **3. Save** Click **Save notifications**. Superlog posts when an error is seen for the first time and when a resolved error happens again. Repeat occurrences of an open or ignored issue don't post. The message shows the exception, service, and time, with **Resolve**, **Silence**, and **Fix in Conductor** buttons. **Silence** sets the issue to **Ignored**. Notifications are off by default. Earlier errors are not posted when you turn them on. An agent with the [Superlog MCP server](/assistants/claude) can turn notifications on with `update_error_notifications`, when you sign in as an owner or admin. ## Start automations from errors Add the **Errors** trigger to an automation to start a run on **New error**, **Error regression**, or both. You can limit it to some services. The agent receives the issue with its newest stack trace, trace ID, and attributes. See [Triggers](/automations/triggers). To alert on error volume instead, click **Create alert**. See [Alerts](/telemetry/alerts). ## Use errors from an agent The [MCP server](/api-reference/mcp) and [REST API](/api-reference/introduction) offer `list_error_issues`, `get_error_issue`, and `update_error_issue`. Follow an issue's trace ID with `get_trace`. # Logs Source: https://docs.superlog.sh/telemetry/logs Search and filter log records, read a log's attributes, and jump to its trace or error. > [!NOTE] > > Telemetry is in early access. To turn it on for your workspace, [book a call](https://cal.com/superlog/yc) or ask in [Discord](https://discord.gg/wJ56aRh8hx). **Explore → Logs** lists the log records your services send, newest first. The page URL holds the search, filters, and time range, so you can share a link to the same view. ## Search Click the search bar or press `/`. As you type, the bar suggests fields and values: * Plain text adds **Search messages for "…"**. It matches the message, or the event name of a log without one. Case is ignored. * `service.name` and `level` filter by service and level. * `trace.id` filters to one trace. Paste a 32-character trace ID to add it directly. * Any attribute key seen in the time range, grouped as **Resource attributes** and **Log attributes**. Pick a field, then an operator (`=` is, `!=` is not), then a value from the suggestions or type your own. You can also type the filter in one go, such as `deployment.environment!=staging` or `log.http.status_code=500`. A key without a prefix is read as a resource attribute unless it matches a listed attribute. Each filter becomes a chip. Click a chip to edit it, or **×** to remove it. Several values of one field match any of them. Different fields must all match. ## Sidebar filters The sidebar lists **Service** and **Level** with counts, and every attribute key below them. Click a key to see its top values and check the ones you want. Up to 10 attribute facets stay open; opening another closes the oldest. Use **Search facets** to find a key. ## Time range The time picker defaults to the last hour. It offers: * Relative ranges from **Last 5 minutes** to **Last 30 days**, plus **Today so far** and **Yesterday**. * Absolute **From** and **To** times with a calendar. * Typed ranges, such as `3h`, `yesterday`, or `14:00 to 15:30`. * A time zone: **Browser time**, **UTC**, or any zone. The arrows beside the range move it earlier or later. **Zoom out** doubles it. A range can be up to 30 days long. Click the refresh button to reload with the current time. The same picker is used on trace search, metrics, and dashboards. ## Results A histogram above the list shows matching logs over time, split into **Error**, **Warn**, and **Other**. The list has these columns: | Column | Shows | | - | - | | **Time** | When the record was written, with milliseconds. The date appears for ranges of a day or more. | | **Level** | The log's severity text. Logs without one show **Unset**. | | **Service** | The `service.name` of the sender. | | **Message** | The log body. | The list shows 100 logs per page. Use **Previous** and **Next** to page through. ## Log details Click a log to open its details. Use the arrows in the header to move to the previous or next log. The panel shows: * The full message. * **Exception**: the exception type, message, and stack trace, when the log has them. * **Attributes**: `event_name`, `trace_id`, and `span_id` first, then log attributes and resource attributes. Use **Filter keys** to find one. Hover an attribute for **Filter**, **Exclude**, and **Copy**. **Filter** and **Exclude** add the value to your search. ## Jump to the trace or error When the log has a trace ID, the panel shows: * **Open trace** opens the trace in the [trace view](/telemetry/traces#trace-inspector). * **Logs in this trace** filters the list to logs with the same trace ID. When the log is at `ERROR` level or above and belongs to an error issue, **Open error** opens the issue. See [Errors](/telemetry/errors). ## Query logs from an agent The [MCP server](/api-reference/mcp) has a `query_logs` tool, and the [management API](/api-reference/introduction) has `POST /telemetry/logs/search`. Use them to let an agent search logs with the same filters. # Metrics Source: https://docs.superlog.sh/telemetry/metrics Pick a metric, aggregate and group it, and add the graph to a dashboard or alert. > [!NOTE] > > Telemetry is in early access. To turn it on for your workspace, [book a call](https://cal.com/superlog/yc) or ask in [Discord](https://discord.gg/wJ56aRh8hx). **Explore → Metrics** lists every metric your services sent in the time range, next to a graph of the one you pick. The page URL holds the metric, filters, aggregation, grouping, chart type, and time range, so you can share a link to the same graph. ## Pick a metric The list on the left groups metrics by the part of the name before the first dot, such as `http` or `process`. Cloud provider metrics, such as CloudWatch, are listed after your own. **Search metrics** matches names, descriptions, units, and attribute keys. When you open the page without a metric, it shows the first one in the list. The header shows the metric's name, its kind (**Gauge**, **Sum**, **Histogram**, **Exp. histogram**, or **Summary**), its unit, which services report it, and how many attributes it has. ## Filter The search bar filters by resource attributes and data point attributes. Pick an attribute, `=` or `!=`, and a value. A graph can have up to 50 filters. ## Aggregation **Aggregation** sets how data points combine in each time step: | Kind | Default | Also offered | | - | - | - | | Sum | **Sum** | Average, Minimum, Maximum, 95th percentile, 99th percentile | | Gauge | **Average** | Sum, Minimum, Maximum, 95th percentile, 99th percentile | | Histogram, exponential histogram | **Count** | Sum, Average, Minimum, Maximum, 95th percentile, 99th percentile | | Summary | | Sum, Average | Histograms open on **95th percentile** and summaries on **Average**. **Count** counts data points and has no unit. ## Group by **Group by** splits the graph into one series per value of an attribute. Each option shows whether it is a data point or resource attribute and how many values it has. Choose **No grouping** for one series. ## Chart Switch between **Lines** and **Bars**. The heading names the aggregation, metric, and grouping, and shows the series count and time step. Drag across the graph to zoom into that window. The time picker works as in [Logs](/telemetry/logs#time-range). Below the graph, a table lists each series with its **Avg**, **Max**, and **Last** value. Click a series to hide or show it. ## Use the graph elsewhere * **Add to dashboard** adds the graph as a widget to an existing dashboard or a **New dashboard**. See [Dashboards](/telemetry/dashboards). * **Create alert** opens a new alert with this metric, its filters, and its grouping filled in. See [Alerts](/telemetry/alerts). ## Query metrics from an agent The [MCP server](/api-reference/mcp) has a `query_metrics` tool, and the [management API](/api-reference/introduction) has `POST /telemetry/metrics/search`. # Synthetic checks Source: https://docs.superlog.sh/telemetry/synthetics Request an HTTP endpoint on a schedule, assert on the response, and get a Slack message when it fails. > [!NOTE] > > Telemetry is in early access. To turn it on for your workspace, [book a call](https://cal.com/superlog/yc) or ask in [Discord](https://discord.gg/wJ56aRh8hx). A synthetic check sends an HTTP request to a URL on a schedule and checks the response. When runs fail, Superlog posts to Slack. When the check passes again, it replies in the same thread. Open **Synthetics**, under **Detect** in the sidebar, and click **New check**. ## Request * **Method**: `GET`, `HEAD`, `POST`, `PUT`, `PATCH`, `DELETE`, or `OPTIONS`. * **URL**: a full `http` or `https` URL. The host must resolve to public addresses. * **Headers**: up to 30. Lock a header to store its value as a secret. Secrets are encrypted, never shown again, and sent only to the URL's host. * **Body**: for methods other than `GET` and `HEAD`. * **Timeout**: 5, 10, 20, or 30 seconds. * **Follow redirects**: on by default, up to 5 redirects. `Authorization` and `Cookie` headers are not sent to another origin after a redirect. ## Success criteria Add up to 20 assertions. A new check starts with **Status code** is `2xx` and **Response time** below 2,000 ms. | Assertion | Checks | | - | - | | **Status code** | A code such as `200`, or a class such as `2xx`. | | **Response time** | The request finished below a number of milliseconds. | | **Header** | A response header's value, or whether it exists. | | **Body** | The body contains, or doesn't contain, some text. The first 1 MB is read. | | **JSON path** | A value in a JSON body, such as `$.status`. | | **TLS certificate** | The certificate expires in more than a number of days. | Each assertion has a **Severity**. **Fails** fails the run. **Degrades** marks the run degraded but not failed. A run also fails when the request can't connect or times out. Click **Test** to send the request once and see the response and which assertions hold. ## Schedule * **Run**: every minute, 5 minutes, 15 minutes, 30 minutes, or hour. * **When a run fails**: **Don't retry**, **Retry once**, or **Retry twice**. Retries happen at once. Only the last attempt counts. ## Notifications Choose a **Slack channel**. Private channels appear once the Superlog app is in them. **Alert** sets how many failed runs in a row start a failure: 1, 2, 3, or 5. Superlog posts once when the check starts failing, with the request, the number of failed runs, where they ran from, and the reason. It replies in the thread when a run passes again. Degraded runs don't post. Turn off **Run this check** to pause it. Click **Create check**. ## Check page The list shows each check's status, latest runs, uptime over 24 hours, average duration, and last run. Click a check to see: * **Uptime** and **Average duration** for the last 24 hours, 7 days, or 30 days. * **Runs** over time, and **Duration by phase** (DNS, connect, TLS, first byte, download). * **Latest runs**. Click a run to see its assertions, timing, and response. The response is kept only for runs that didn't pass. * **Failures**: each time the check failed, how long it lasted, and why. Runs are kept for 30 days. Use **Edit** to change the check, **Delete** to remove it and its history, and **Copy as Terraform** for the [Terraform provider](/developer/terraform). ## Metrics In workspaces with telemetry, each run is also sent to your metrics: | Metric | Value | | - | - | | `synthetic_check.up` | `1` when the run passed or was degraded, `0` when it failed. | | `synthetic_check.duration` | How long the request took, in ms. | | `synthetic_check.phase.duration` | Each phase's time, in ms, with a `synthetic_check.phase` attribute. | They come from the `superlog-synthetics` service with `synthetic_check.name` and `synthetic_check.id` attributes. Chart them on [dashboards](/telemetry/dashboards) or build [alerts](/telemetry/alerts) on them, for example when the average of `synthetic_check.duration` is above a threshold. ## Start automations from failures A failure message starts automations that watch its Slack channel with **New message in channel** or **Message posted or app mentioned**. Each automation runs once per failure and replies in the thread. See [Triggers](/automations/triggers#slack). ## Manage checks from an agent The [MCP server](/api-reference/mcp) offers `create_synthetic_check`, `update_synthetic_check`, `get_synthetic_check`, `list_synthetic_checks`, and `delete_synthetic_check`. Use `list_slack_channels` for the channel and integration IDs. The same operations are in the [REST API](/api-reference/introduction). # Traces Source: https://docs.superlog.sh/telemetry/traces See request rate, errors, and latency per service, search traces, and inspect each span. > [!NOTE] > > Telemetry is in early access. To turn it on for your workspace, [book a call](https://cal.com/superlog/yc) or ask in [Discord](https://discord.gg/wJ56aRh8hx). **Explore → Traces** has two pages: **Overview** for a service's health, and **Search** for individual traces. ## Traces overview The overview summarizes requests. A request is a span that enters a service: a server or consumer span, or the root span of a trace. Pick a **Service** or keep **All services**. When spans carry the `deployment.environment` resource attribute, an **Environment** list appears too. Choose a range of **15m**, **1h** (the default), **6h**, **24h**, or **7d**. Turn on **Live** to reload every 10 seconds. Three tiles chart the range: * **Requests** per minute, with errors marked. * **Error rate** as a share of requests. * **p95 latency**. Bars turn orange from 500 ms and red from 1 s. Below them: * **Operations**: the top request span names, with **Req/min**, **Errors**, and **p95**. Click one to search its traces. * **Dependencies**: outgoing client calls by p95 latency. Each is named by `peer.service`, `server.address`, `net.peer.name`, or `db.system`, whichever the span has, and otherwise by its span name. * **Top errors**: failing spans grouped by status message, with how many traces they hit and when they were first seen. Click one to search those traces, or **View all in Search**. ## Trace search **Traces → Search** lists traces that started in the time range, newest first. It uses the same time picker as [Logs](/telemetry/logs#time-range). The search bar works like the log search. Press `/` to focus it. Fields include: * `service.name`, `status` (**Error**, **OK**, **Unset**), and `operation` (the span name). Plain text filters to that exact span name. * `duration` with `>=` and a value such as `500ms`, `1s`, or `1m`, up to 60 minutes. * `trace.id`. Paste a trace ID to open that trace directly. * Any resource or span attribute seen in the range. The sidebar has **Service**, **Status**, **Span name**, and **Trace duration** (**Over 100 ms** to **Over 5 s**), and every attribute key below them. A trace matches when any of its spans matches the filters. Its row describes the whole trace: | Column | Shows | | - | - | | **Started** | When the first span started. | | **Root span** | The span without a parent, its service, and how many services the trace crossed. | | **Duration** | From the first span's start to the last span's end. | | **Spans** | How many spans the trace has. | | **Status** | **Error** if any span failed, otherwise **OK**. | The histogram above counts matching spans by status. The list shows 50 traces per page. ## Trace inspector Click a trace to open it in a panel beside the list. Use the arrows to move to the previous or next trace, or **Open full page** for a page of its own. The header shows the request: method, route, and HTTP status code when the root span has them. Below it are the root service, duration, and counts of spans, services, and errors, with the **Trace ID** to copy. ### Waterfall The **Waterfall** tab draws each span on a timeline, nested under its parent and colored by service. * **Find a span or attribute** matches span names, services, span IDs, and attribute keys and values. Matching spans stay visible with their parents. * **Show only errors** hides spans that didn't fail. * **Collapse all** and **Expand all** fold the tree. Click a span's arrow to fold one branch. The inspector opens on the first failing span, or the root span if none failed. ### Selected span Click a span to see its name, service, kind, duration, start offset, and **Span ID**. A failing span shows its error message and stack trace. Attributes are grouped: * **HTTP**: `http.*`, `url.*`, and `server.*` attributes. * **Request context**: the span's other attributes. * **Resource attributes**: the sending process. Collapsed by default. Hover an attribute for **Filter**, **Exclude**, and **Copy**. **Filter** and **Exclude** add it to your trace search. **Logs in this span** lists the logs the span wrote. **Open in Logs** opens them in [Logs](/telemetry/logs). ### Logs and services * **Logs** lists every log in the trace. Click a message to select the span that wrote it. * **Services** lists each service with its spans, errors, and total **Time in spans**. ## Query traces from an agent The [MCP server](/api-reference/mcp) has `query_traces` and `get_trace`. The [management API](/api-reference/introduction) has `POST /telemetry/traces/search` and `GET /telemetry/traces/{traceId}`.