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

# Graylog

> Connect Graylog to CloudThinker for read-only log search, cluster and stream inspection, and message count analysis

Connect your Graylog cluster to let [Alex](/guide/agents/alex) (Cloud Engineer) and [Kai](/guide/agents/kai) (Kubernetes Engineer) check cluster health, list your streams and index sets, search recent messages, and count messages grouped by a field.

Graylog authenticates with a **REST API access token** belonging to a Graylog user. The connection is **read-only**: CloudThinker gives agents no way to reach the Graylog endpoints that change things.

## Prerequisites

* A **Graylog cluster** reachable from CloudThinker over **HTTPS**.
* A **least-privilege Graylog user** for CloudThinker with the **Reader** role.
* **Read access shared on the streams and index sets** you want agents to read — the Reader role alone is not enough, see [Required permissions](#required-permissions).
* A **REST API access token** for that user.

## Setup

<Steps>
  <Step title="Create a read-only Graylog user">
    In Graylog, go to **System → Users and Teams** and create a user for CloudThinker with the **Reader** role — Graylog's read-only baseline. A dedicated user, rather than a person's account, keeps the scope visible and revocable in one place.
  </Step>

  <Step title="Share the streams and index sets with that user">
    The Reader role by itself grants no access to your entities — Graylog controls those by sharing. Share each stream and index set CloudThinker should read with the new user at the **Viewer** access level.

    Skip this and Graylog returns an empty list of streams instead of an error, which looks like a Graylog with no streams rather than a missing permission.
  </Step>

  <Step title="Create a REST API access token">
    Still in **System → Users and Teams**, find the user, open the **More** drop-down, and select **Edit tokens**. Enter a token name, set the **TTL** using ISO 8601 duration format, and click **Create Token**.

    Copy the token immediately — Graylog does not show it again.
  </Step>

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

    * **Graylog base URL**: your Graylog web/API root, such as `https://graylog.example.com:9000`
    * **API token**: the token you just created
    * **TLS certificate**: leave on **Verify TLS certificate**

    Click **Connect**. CloudThinker reads your cluster status to verify the token and shows a **Connected** status with the node count it found.
  </Step>
</Steps>

<Warning>
  Graylog access tokens expire — the default TTL is **30 days**, after which the connection fails with a rejected-token error. Set a TTL that matches your rotation schedule and update the connection before the old token expires. An administrator can change the default under **System → Configurations → Users**.
</Warning>

## Connection details

| Field                      | Description                                                           | Example                            |
| -------------------------- | --------------------------------------------------------------------- | ---------------------------------- |
| **Graylog base URL**       | Graylog web/API base URL, with no `/api`, path, query, or credentials | `https://graylog.example.com:9000` |
| **API token**              | REST API access token for the read-only Graylog user                  | —                                  |
| **Verify TLS certificate** | Whether to verify the Graylog TLS certificate                         | `true`                             |

Enter the web/API root only — CloudThinker adds `/api` itself and rejects a URL that carries anything else. The URL must use `https`, because the token is sent with every request; plain `http` is accepted only when Graylog runs on the same machine as CloudThinker.

## Required permissions

The token needs **read** access, and Graylog splits that across two layers:

| Layer              | What to grant                                          | Why                                                                                                               |
| ------------------ | ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------- |
| **Role**           | The **Reader** role on the CloudThinker user           | Graylog's read-only baseline; every user holds either Reader or Admin                                             |
| **Entity sharing** | Each **stream** and **index set** shared at **Viewer** | Graylog controls individual entities by sharing; with nothing shared, a Reader has no access to Graylog resources |

No Graylog permission beyond read is ever needed — CloudThinker exposes no Graylog write action, so granting write access only widens what a leaked token could do.

<Note>
  The Reader role on its own is the most common misconfiguration. Graylog returns an empty list of streams and a success code rather than a 403, so the connection tests as **Connected** while agents report that no streams exist. If discovery shows no streams on a cluster that has them, share the streams and index sets with the token's user.
</Note>

## Agent capabilities

Once connected, agents have read access to your Graylog cluster.

| Capability                | Description                                                                               |
| ------------------------- | ----------------------------------------------------------------------------------------- |
| **Cluster health**        | Summarize node count, Graylog versions, and cluster health                                |
| **Streams & index sets**  | List streams and index sets, and review routing rules, retention, and index rotation      |
| **Log search**            | Search messages with a query over a recent time window and return a sample of the matches |
| **Counts & distribution** | Count messages grouped by one field to find the noisiest source, service, or error class  |
| **Ingestion checks**      | Spot disabled streams and sources whose ingestion stopped                                 |

Searches and counts are bounded: the time window reaches back at most 30 days, and results return at most 100 rows or groups. Agents tell you which window and limit they used, and say when a result was cut short instead of presenting it as a total.

### Verify the connection

```text theme={null}
@alex run Graylog discovery and summarize cluster health, node count, and the streams and index sets this token can read
```

### Example prompts

```text theme={null}
@alex #report 5xx errors from the api-gateway in Graylog over the last 6 hours
@alex #report Graylog message counts by source over the last 24 hours and anything that stopped sending
@kai #recommend a next step for the errors from the payments pods in Graylog over the last hour
```

## Troubleshooting

<Accordion title="Graylog rejected the API token">
  The token expired, was revoked, or was copied incompletely. Graylog tokens expire at their TTL, 30 days by default. Create a new token under **System → Users and Teams → More → Edit tokens** and update the connection.
</Accordion>

<Accordion title="The token cannot read the cluster status">
  The token is valid but its Graylog user lacks the read role. Give the user the **Reader** role, then test the connection again.
</Accordion>

<Accordion title="Discovery reports no streams on a cluster that has streams">
  The user has the Reader role but no streams shared with it, so Graylog returns an empty page instead of denying the request. Share each stream and index set with that user at **Viewer** access. An empty list here means the token cannot see those streams, not that Graylog has none.
</Accordion>

<Accordion title="The endpoint did not answer as Graylog, or is unreachable">
  The base URL points at the wrong root, already contains `/api`, or nothing answered at all. Reconnect with the web/API root only, such as `https://graylog.example.com:9000`, and check the host, port, and network path from CloudThinker.
</Accordion>

<Accordion title="Graylog URL must use HTTPS, or TLS verification was refused">
  A plain-`http` URL, or **Skip TLS verification**, is rejected for a remote Graylog because either would expose the token — in clear text, or to whichever server answers. Serve Graylog over HTTPS, install a trusted certificate, and keep **Verify TLS certificate** on.
</Accordion>

<Accordion title="Results look truncated, or Graylog rate-limited the request">
  The query hit the result limit, the search timed out, or Graylog (or a proxy in front of it) returned HTTP 429. A search that times out does not tell you how many messages matched — narrow the query, shorten the time window, or group by a more specific field, then ask again.
</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.

- **Share only the streams you want read** — entity sharing, not the role, decides which logs agents can see.
- **Watch the token TTL** — a token that expires silently breaks the connection; rotate it on schedule and update the connection with the new value.

## Related

<CardGroup cols={2}>
  <Card title="Coralogix Connection" icon="https://mintcdn.com/cloudthinker/CGWam0VVP8R5KVLk/images/icons/coralogix.svg?fit=max&auto=format&n=CGWam0VVP8R5KVLk&q=85&s=b93db8be4df83bdef5ac59815fd38517" href="/guide/connections/coralogix" width="139" height="139" data-path="images/icons/coralogix.svg">
    Log search, metrics, traces, and incident triage
  </Card>

  <Card title="Elasticsearch Connection" icon="https://mintcdn.com/cloudthinker/aLd-ttc-SCW-aFky/images/icons/elasticsearch.svg?fit=max&auto=format&n=aLd-ttc-SCW-aFky&q=85&s=c7389cfcd0bc8d303aeeb68bd19199ca" href="/guide/connections/elasticsearch" width="24" height="24" data-path="images/icons/elasticsearch.svg">
    Log analysis, index management, and search performance optimization
  </Card>
</CardGroup>