> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloudthinker.io/llms.txt
> Use this file to discover all available pages before exploring further.

# SigNoz

> Connect SigNoz to CloudThinker to investigate service latency, search logs, audit alert rules, and drill into distributed traces across your stack

Connect your SigNoz instance to enable CloudThinker agents to investigate service latency, search and aggregate logs, audit alert rules, and drill into distributed traces across your stack.

SigNoz authenticates with a **Service Account API key** scoped to a role (`signoz-viewer` for read-only access, `signoz-admin` for write access).

***

## Supported platforms

| Platform                 | Support                |
| ------------------------ | ---------------------- |
| **SigNoz Cloud**         | All tenants            |
| **SigNoz (self-hosted)** | Self-managed instances |

SigNoz Cloud and self-hosted share the same interface, so the setup steps below are identical for both.

***

## Prerequisites

* A **SigNoz Cloud or self-hosted instance**.
* A **Service Account** to mint an API key (use `signoz-viewer` for read-only access or `signoz-admin` if CloudThinker should make changes).
* Your **SigNoz base URL**.

***

## Setup

<Steps>
  <Step title="Create a service account">
    In SigNoz, open **Settings → Workspace Settings → Service Accounts** and click **New Service Account**. Enter a name (e.g. `cloudthinker-svc`) and click **Create Service Account**.
  </Step>

  <Step title="Assign a role">
    On the **Overview** tab, use the **Roles** dropdown to pick `signoz-viewer` for read-only access or `signoz-admin` if CloudThinker should make changes. Click **Save Changes** so the role takes effect.
  </Step>

  <Step title="Create an API key">
    Switch to the **Keys** tab and click **Add Key**. Enter a key name (e.g. `cloudthinker-key`), optionally set an expiration date, click **Create Key**, and copy the key.
  </Step>

  <Step title="Add the connection in CloudThinker">
    Navigate to **Connections → SigNoz** and enter:

    * **SigNoz URL**: your instance base URL, e.g. `https://<hash>.signoz.cloud` (base URL only, no path, or requests return a 404)
    * **API Key**: the key you copied
    * **Log Level** (optional): leave as `info` unless you are debugging

    Click **Connect**. CloudThinker verifies the credentials and shows a **Connected** status.
  </Step>
</Steps>

***

## Connection details

| Field                | Description                                                   | Example                       |
| -------------------- | ------------------------------------------------------------- | ----------------------------- |
| **SIGNOZ\_URL**      | Base URL of your instance, no path suffix                     | `https://<hash>.signoz.cloud` |
| **SIGNOZ\_API\_KEY** | Service Account key                                           | Copied from the Keys tab      |
| **LOG\_LEVEL**       | MCP server log verbosity: `debug`, `info`, `warn`, or `error` | `info`                        |

***

## Required permissions

* **`signoz-viewer`** grants read-only access: querying services, logs, traces, metrics, and inspecting alerts, dashboards, and views.
* **`signoz-admin`** additionally grants write access: creating, updating, or deleting alerts, dashboards, views, and channels.
* Write operations also require explicit [approval](/guide/approval) in CloudThinker before they run.

<Tip>
  Start with `signoz-viewer` for read-only investigation. Assign `signoz-admin` only when you want agents to manage alerts or dashboards.
</Tip>

***

## Agent capabilities

Once connected, agents can perform read operations across your observability data and a set of approval-gated write operations.

| Capability                | What the agent can do                                                                                     |
| ------------------------- | --------------------------------------------------------------------------------------------------------- |
| **Services (APM)**        | List instrumented services, inspect top operations by latency                                             |
| **Logs**                  | Search logs by time and filter, aggregate and group by patterns                                           |
| **Traces**                | Search traces, fetch full trace waterfalls, drill into dependencies                                       |
| **Metrics**               | List metrics and run time-series queries                                                                  |
| **Dashboards**            | List and inspect dashboards and templates                                                                 |
| **Alerts**                | List alert rules, inspect a rule and its state-transition history; create, update, or delete (admin only) |
| **Saved views**           | List, inspect, create, update, or delete saved query views (admin only)                                   |
| **Notification channels** | List, inspect, create, update, or delete channels (admin only)                                            |
| **Documentation**         | Search and fetch SigNoz documentation                                                                     |

<Warning>
  Write operations change live alerting and dashboards. CloudThinker requires explicit [approval](/guide/approval), naming the resource, before any write runs. Deletes are irreversible.
</Warning>

### Verify the connection

```text theme={null}
@tony list SigNoz services and confirm that metrics and traces are reachable
```

### Example prompts

```text theme={null}
@tony find the slowest operations for the checkout service
@tony search error logs and group spikes by service
@tony audit SigNoz alert rules and flag misconfigured thresholds
```

***

## Troubleshooting

<Accordion title="Connection fails with 401 Unauthorized">
  Verify the API key is correct and has not been revoked. Confirm you clicked **Save Changes** after assigning the role, then re-mint the key.
</Accordion>

<Accordion title="Every request returns 404">
  `SIGNOZ_URL` has an extra path suffix. Set it to the base URL only, e.g. `https://<hash>.signoz.cloud`, with no `/api/v1`.
</Accordion>

<Accordion title="403 Forbidden">
  The service account's role is too low for the action. Assign `signoz-admin` for write operations, then click **Save Changes**.
</Accordion>

<Accordion title="Searches return no results">
  Log, trace, and metric searches need a time range. Ask the agent to use a recent window (e.g. the last 15 minutes) and widen it only if needed.
</Accordion>

***

## 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.

- **Base URL only** — set `SIGNOZ_URL` to the root URL with no path suffix; a trailing path causes all requests to return 404.
- **Approval for writes** — keep write operations approval-gated so alert and dashboard changes stay deliberate.

***

## Related

<CardGroup cols={2}>
  <Card title="Datadog Connection" icon="https://mintcdn.com/cloudthinker/aLd-ttc-SCW-aFky/images/icons/datadog.svg?fit=max&auto=format&n=aLd-ttc-SCW-aFky&q=85&s=e8382167f2a1eb1e00971b5f4d703d48" href="/guide/connections/datadog" width="24" height="24" data-path="images/icons/datadog.svg">
    Observability and monitoring
  </Card>

  <Card title="Grafana Connection" icon="https://mintcdn.com/cloudthinker/aLd-ttc-SCW-aFky/images/icons/grafana.svg?fit=max&auto=format&n=aLd-ttc-SCW-aFky&q=85&s=c1329049025cd3c3a0909b400baef7be" href="/guide/connections/grafana" width="24" height="24" data-path="images/icons/grafana.svg">
    Dashboards and metrics
  </Card>
</CardGroup>