GitHub, OTel & more

Besides alert channels like Slack, email and PagerDuty, SutramX connects to the tools your engineering team already uses. This page covers the GitHub issues integration, the OpenTelemetry export, Zapier, and where to find deploy tracking.

Alert channels are set up in Alerts → Channels & API, on the Integrations tab. Only the workspace owner can connect, edit or disconnect them in the dashboard.

GitHub issues#

The GitHub integration opens an issue in a repository when an incident starts, then comments on it and closes it when the monitor recovers. Use it when your team tracks outages in GitHub, or to keep a record of incidents next to the code.

What happens:

• Incident starts: SutramX opens an issue titled [SutramX] <monitor name> is down. The body lists the monitor, its URL, the region, the error, the start time and a link to the incident. The issue gets the incident label if the repository allows it.
• Monitor recovers: SutramX comments <monitor name> recovered after N min. Closing automatically. and closes the issue as completed.
• Each incident gets at most one issue per GitHub connection, even if the alert is retried.
• The issue link is also shown on the incident in SutramX (github_issue_url in the API).

The GitHub integration follows the same plan availability as webhook alerts. See Plans & limits.

Connect with the GitHub App#

If the GitHub card shows a Connect with GitHub button, this is the quickest option:

1. Go to Alerts → Channels & API and find the GitHub card.
2. Click Connect with GitHub.
3. In GitHub, install the SutramX GitHub App on the repositories that should get incident issues. The app only gets access to issues.
4. Back in SutramX, choose the repository in Choose a repository and click Connect.

To send issues to another repository as well, click Connect another with GitHub.

Connect with a personal access token#

If you prefer not to install the app, or the button isn't shown, use a fine-grained personal access token:

1. In GitHub, go to Settings → Developer settings → Fine-grained tokens → Generate new token.
2. Under Repository access, choose only the repository that should get incident issues.
3. Under Permissions, set Issues to Read and write.
4. Generate the token and copy it.
5. In SutramX, open the GitHub card. If you see Connect with GitHub, click Use a personal access token instead.
6. Fill in the fields and click Connect.

When you connect, SutramX checks the token and repository automatically. Send test also checks access and that issues are enabled on the repository. It does not create an issue.

Choose which monitors open issues#

By default a connection gets alerts for every monitor. To limit it, open the connection's menu, choose Routing, then click Save routing. You can pick all monitors, specific monitor groups, or specific monitors, and whether degraded checks count. For example, connect one repository per team and route each team's monitor group to its own repository.

You can add up to 10 GitHub connections, for example one per repository.

Troubleshooting GitHub issues#

OpenTelemetry export#

The OpenTelemetry export sends every check result to your own OpenTelemetry collector or tracing backend as a span. You can then chart SutramX checks next to your application traces, or alert on them with the tools you already use.

What is exported#

Each check run becomes one span, sent as OTLP/HTTP JSON.

Span attributes:

Resource attributes: service.name (your setting, default sutramx-checks), service.namespace = sutramx, sutramx.workspace.id and telemetry.sdk.name = sutramx. The instrumentation scope is sutramx.checks.

Query strings and user names/passwords in monitor URLs are never exported, because they often contain tokens.

Set up the export#

1. Open Account settings → OpenTelemetry.
2. Fill in the fields below.
3. Tick Export check results.
4. Click Save.
5. Click Send test span and check that it arrives in your backend.

Header values are stored encrypted and never shown again. The settings show only the header names. To change them, click Replace headers and enter the full set.

To stop exporting, untick Export check results and save, or click Remove to delete the settings.

Delivery and status#

• Spans are sent in batches, about every 5 seconds or every 200 spans.
• If your endpoint fails, SutramX drops that batch and backs off, waiting up to 10 minutes between attempts. Spans are not replayed later.
• Up to 2,000 spans are buffered per workspace. Beyond that the oldest are dropped.
• The settings show On or Off, when the last export succeeded, how many spans were sent, and the last error.

Configure the export with the API#

You can also manage the export with an API key that has Automation access:

curl -s -X PUT "https://api.sutramx.com/automation/otel" \
  -H "Authorization: Bearer $SUTRAMX_AUTOMATION_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "endpoint": "https://otlp.example.com",
    "service_name": "sutramx-checks",
    "headers": { "Authorization": "Bearer <collector token>" }
  }'

The response shows the settings and delivery status. Header values are never returned, only header_names:

{
  "configured": true,
  "enabled": true,
  "endpoint": "https://otlp.example.com/v1/traces",
  "header_names": ["Authorization"],
  "service_name": "sutramx-checks",
  "last_export_at": null,
  "last_error": null,
  "last_error_at": null,
  "consecutive_failures": 0,
  "exported_spans": 0
}

GET /automation/otel reads the settings, DELETE /automation/otel removes them, and POST /automation/otel/test sends one test span (10 tests per 15 minutes).

Troubleshooting the export#

Zapier#

Use Zapier to send SutramX alerts to apps that don't have a built-in channel, such as a spreadsheet, a ticketing tool or an SMS gateway of your own.

1. In Zapier, create a Zap with the Webhooks by Zapier → Catch Hook trigger.
2. Copy the custom webhook URL Zapier gives you.
3. In SutramX, go to Alerts → Channels & API, open the Zapier card and paste the URL into Link from Zapier.
4. Click Connect. SutramX sends a test event to the hook, which you can use to map fields in Zapier.

Zapier receives the same events as other chat channels: monitor down and recovered alerts, SSL certificate and domain expiry warnings, and maintenance notices. Zapier follows the same plan availability as webhook alerts. For your own code, a webhook gives you signed deliveries instead.

Deploy events#

SutramX can record your deployments and show them next to incidents, so you can see whether a deploy caused an outage. You can send deploys from GitHub or GitLab webhooks, or from your CI with the API. Deploy events are on the Deploy events tab of Alerts → Channels & API. See Deployment correlation for the setup.