Skip to main content
Connect SigNoz Cloud or a self-hosted SigNoz instance to let CloudThinker agents rank a service’s slowest operations, search and group logs, open a full trace waterfall, query metrics, and review alert rules and their history. You give CloudThinker two values: your SigNoz base URL and a Service Account API key. The setup is the same for SigNoz Cloud and self-hosted.

​
Prerequisites

  • A SigNoz Cloud or self-hosted SigNoz instance with at least one instrumented service sending telemetry. SigNoz creates services from your applications’ telemetry, so agents can’t create one for you.
  • A SigNoz user with the SigNoz-Admin role, who can create a Service Account and its API key.
  • Your SigNoz base URL: https://<your-tenant>.signoz.cloud for SigNoz Cloud, or the address you open SigNoz at for self-hosted, such as https://signoz.internal.example.com.
  • For self-hosted SigNoz: the instance must accept connections from CloudThinker Cloud. To allowlist CloudThinker’s egress IPs, you need the current list. These docs don’t publish CloudThinker’s egress IP list: ask your CloudThinker contact, or contact us. See Reaching private services for other options.
  • The Admin role in the CloudThinker workspace, which you need to add connections. See Roles.

​
Setup

1

Create a Service Account

In SigNoz, open Settings → Service Accounts, click New Service Account, and name it something you’ll recognize later, such as cloudthinker. The steps are the same on SigNoz Cloud and self-hosted.
2

Pick its role

On the account’s Overview tab, pick the narrowest role from the Roles dropdown:Click Save before you create a key. SigNoz-Admin can also manage users, roles, and service accounts, so pick it only when you need it.
3

Create an API key

Open the account’s Keys tab, click Add Key, name it (for example cloudthinker-key), set an expiration if your policy needs one, and copy the key. SigNoz shows it only once.
4

Add the connection in CloudThinker

In the sidebar, click More → Workspace settings → Connections, stay on the Builtin Connections tab, and select SigNoz. Fill in:
  • SIGNOZ_URL: the base URL only, for example https://<your-tenant>.signoz.cloud. Don’t add /api/v1 or any other path.
  • SIGNOZ_API_KEY: the key you copied.
  • LOG_LEVEL: leave it at Info. It sets how much detail the connection writes to CloudThinker’s diagnostic logs, which support uses when troubleshooting.
Click Connect.Success state: SigNoz shows Connected.

​
Connection details

​
Required permissions

Agents can do exactly what the Service Account’s role allows, and SigNoz enforces it.
  • SigNoz-Viewer covers every read in the capability table below.
  • SigNoz-Editor adds dashboard and alert writes. SigNoz doesn’t document Editor access to saved views or notification channels, so use SigNoz-Admin for those.
  • SigNoz-Admin adds every write, plus user, role, and service account management in SigNoz.
Every change an agent makes goes through your workspace’s Approvals first. On the default Auto · Rules + AI · Ask me mode, AI judgment can let a safe change run without asking — and an Allow Rule can too, once CloudThinker turns on Rule enforcement for your workspace. Choose Manual to approve every change yourself. A Rule can make CloudThinker ask first for a write, or refuse it outright.
Start with SigNoz-Viewer. Move to SigNoz-Editor for dashboard and alert changes, or SigNoz-Admin only when you want agents to manage saved views or channels for you.

​
Agent capabilities

Log, trace, and metric searches always run over a time window. Agents start with the last 15 minutes and widen it when nothing comes back, so name a window in your prompt if you care about a specific period.
A SigNoz delete can’t be undone: a deleted alert loses its history, and deleting a notification channel leaves its routed alerts with nowhere to send. Agents show you the current record before an update or delete, so read it before you approve.

​
Verify the connection

Expect a count and sample of services, dashboards, and alert rules, plus how many alerts are firing now.

​
Example prompts

​
Troubleshooting

SIGNOZ_URL has a path on the end. Set it to the base URL only, such as https://<your-tenant>.signoz.cloud, with no /api/v1.
The key is wrong, expired, or revoked. Create a new key on the Service Account’s Keys tab and update SIGNOZ_API_KEY.
The Service Account’s role doesn’t allow the action. A SigNoz-Viewer key returns this on any write. A SigNoz-Editor key may return it on saved view and notification channel writes, since SigNoz doesn’t document Editor access to those. Change the role in SigNoz if you want agents to make that change.
Nothing matched in the window searched. Ask for a wider window, such as the last 6 hours, or drop the filter and add it back one clause at a time.
Your SigNoz instance is rate limiting or restarting. Wait a minute and ask again. On self-hosted SigNoz, check the query service’s health.

​
Security

  • Least privilege — grant only the permissions the agents need for your use case; start read-only and widen later.
  • Read-only by default — use read-only credentials unless you want agents to make changes through this connection.
  • Rotate credentials — rotate keys and tokens on your normal schedule; CloudThinker picks up the new value when you update the connection.
  • Revoke on offboarding — remove the credential at the provider when you delete a connection or a teammate leaves.
  • One Service Account for CloudThinker: don’t reuse a teammate’s key. A dedicated account lets you revoke CloudThinker’s access without touching anyone else’s.
  • Set a key expiration: rotate the key and update SIGNOZ_API_KEY before it lapses, or the connection stops with 401 errors.

Approvals

Decide which SigNoz writes run, wait for a person, or are refused.

Grafana

Connect Grafana dashboards and data sources.