# Overview Your AI SRE teammate Cleric is an AI SRE that investigates production issues. When alerts fire or you need to investigate problems, Cleric queries logs, metrics, and system state to identify root causes and recommend solutions. ### What Cleric Does Cleric connects to your existing observability stack and performs the same investigation steps your engineers would. Cleric can be configured to: 1. **Automatically investigate alerts**: Configure triggers that route matching Slack alerts to the right agent 2. **On-demand investigation**: Investigate production issues when prompted, regardless of alert status For every investigation, Cleric: * **Collects evidence**: Uses tools like kubectl, Datadog APIs, Prometheus queries, and source code to collect relevant data * **Conducts root cause analyses**: Correlates its findings across logs, metrics, and infrastructure changes * **Communicates clearly**: Delivers findings with actionable recommendations and next steps ### Next Steps * [Concepts](/meet-cleric/concepts) - Understand core terminology * [How Investigations Work](/usage/how-investigations-work) - Understand the issue lifecycle from creation to resolution * [Supported Integrations](/integrations/supported-integrations) - Browse available integrations * [Security & Data Privacy](/security/security-data-privacy) - Review security policies # How Cleric Works How Cleric investigates and learns Cleric connects to your existing observability stack and infrastructure through read-only integrations. When an investigation starts, Cleric queries your systems to gather evidence, correlates findings across data sources, and delivers results in Slack. Through each investigation, Cleric learns your environment and improves its analyses. ## Architecture ## Investigation Flow 1. **Trigger**: An alert fires, you mention @Cleric in Slack, or you start an investigation from the web app 2. **Context retrieval**: Cleric recalls relevant memories and environment knowledge 3. **Planning**: Cleric analyzes the problem and creates an investigation plan 4. **Data gathering**: Cleric queries your connected integrations for relevant logs, metrics, and system state 5. **Correlation**: Cleric connects evidence across systems to identify patterns and root causes 6. **Results**: Cleric posts findings to Slack with evidence links and recommended actions ## Learning Cleric builds knowledge of your environment through two mechanisms: * **Environment extraction**: Cleric automatically discovers naming patterns, service relationships, and infrastructure topology from the data it queries during investigations * **Memories**: Facts learned from your conversations, such as service dependencies or known issues, that Cleric recalls in future investigations See [How Cleric Learns](/learning/how-cleric-learns) for details. ## Data Flow Cleric runs in a dedicated, single-tenant environment. Your data never mixes with other customers. * **Integrations**: Cleric authenticates using scoped credentials you provide (API keys, service accounts, tokens) * **Queries**: All queries are read-only by default * **Storage**: Cleric stores investigation data (queries made, reasoning, responses) but does not store your observability data. Logs, metrics, source code, etc. are queried at runtime and not persisted. * **Communication**: Results are delivered via Slack or the Cleric web interface # Concepts Core concepts for working with Cleric ### Issues An **Issue** is a tracked problem that Cleric investigates. Issues originate from monitoring alerts or on-demand requests. A single issue can collect multiple related alerts. Each issue contains the complete investigation history from start to resolution. See [How Investigations Work](/usage/how-investigations-work). ### Integrations An **Integration** is a credential configuration that enables Cleric to authenticate with your infrastructure systems. You configure integrations once by providing credentials (API keys, tokens, service accounts), after which Cleric uses standard CLIs and APIs (`kubectl`, `gh`, `aws`, etc.) to query data during investigations. Examples: * **Datadog**: API credentials for querying metrics, logs, and monitors * **AWS**: Role-based access for CloudWatch logs, metrics, and resource inspection * **GitHub**: Access to repositories, commit history, and workflow logs Most integrations use read-only access. The GitHub integration includes write permissions by default to enable creating issues and pull requests as a result of investigation findings. View the full list of integrations, what data they access, and their setup instructions in [Supported Integrations](/integrations/supported-integrations). ### Agents An **Agent** is a named workflow with instructions that Cleric runs against an issue. Cleric ships with one built-in agent (`investigate`) for deep root-cause analysis. You can create custom agents with your own instructions to encode runbooks or specialize on a service or alert type. See [Configuring Automations](/setup/agents-and-triggers#agents). ### Triggers A **Trigger** is a rule that runs an agent automatically when a matching event fires. Each trigger has a type: **Bot message** fires when a bot message posted in a Slack channel matches the trigger's keywords (evaluated top-down per channel, first match wins), and **Scheduled** fires on a recurring cron schedule. See [Configuring Automations](/setup/agents-and-triggers#triggers). ### Memories A **Memory** is a fact or procedure that Cleric learns from your conversations and uses to improve future investigations. Memories capture infrastructure details, service dependencies, investigation preferences, and other operational knowledge. Cleric proposes memories based on what you share during investigations. You can accept or reject each proposal. ### How Cleric Communicates Cleric's responses include clear reasoning to help you understand and validate its analysis: * **Evidence Summary**: What data supports the conclusion * **Reasoning Process**: How the evidence connects to the conclusion * **Recommended Actions**: Specific next steps * **Follow-up Questions**: Additional access or information that might be needed This transparency helps you quickly assess conclusions and decide on appropriate responses. # Quick Start Get started with Cleric Cleric investigates production issues through Slack or the web interface. This guide walks through connecting Cleric to your environment and running your first investigation. ## Connect Cleric to Your Environment {% hint style="info" %} Using Claude Code, Codex or Cursor? Your coding agent can do these steps for you. See [Setting Up with a Coding Agent](/setup/setting-up-with-a-coding-agent). {% endhint %} The integrations you configure determine what Cleric can investigate and the context it draws on. Connect them in this order: ### 1. Slack Invite Cleric to your alerting and incident channels in [Slack](/integrations/supported-integrations#slack). Cleric analyzes the channel history to identify common problems and their resolutions. It also replays past alerts to identify patterns and access limitations, so that it's ready to investigate when an alert comes in live. Cleric only learns from channels where it is a member, so add it to every channel where you want it active. ### 2. Where Your Workloads Run Connect the platform that runs your services, e.g. [Elastic Kubernetes Service](/integrations/supported-integrations#elastic-kubernetes-service), [Elastic Container Service](/integrations/supported-integrations#amazon-web-services), or your own [Kubernetes](/integrations/supported-integrations#kubernetes) control plane. Cleric uses this to discover your service catalog (which workloads exist, how they relate) and to query the live state of your workloads and infrastructure events during investigations. ### 3. Observability Connect your logging, metrics, and tracing systems. Cleric queries them during investigations, mapping services to their identifiers and learning each system's query conventions (filter syntax, tag schemes, metric naming). See [supported integrations](/integrations/supported-integrations) for the full list. {% hint style="info" %} Cleric begins calibrating to your environment as soon as you connect your first integration. See [How Cleric Learns](/learning/how-cleric-learns#calibration) for more. {% endhint %} ## Your First Investigation ### Start an Investigation You can start investigations from Slack or the web interface. **From Slack:** In any channel where Cleric is present, mention @Cleric with your question: {% code overflow="wrap" %} ``` @Cleric Investigate why the payment API response times are higher than usual. ``` {% endcode %} **From the Web:** 1. Go to `.app.cleric.ai` 2. Click "New issue" 3. Describe the issue 4. Cleric begins analysis immediately ### Complete Investigation Example Here's what a full investigation looks like from start to finish: **Your question:** {% code overflow="wrap" %} ``` @Cleric Investigate why the payment API response times are higher than usual. ``` {% endcode %} **Cleric's investigation:** {% code overflow="wrap" %} ``` **Root Cause:** Database query performance degradation on pricing-api **Timeline:** • 2:15 PM: Query latency started increasing • 2:20 PM: P95 API latency exceeded 500ms threshold • Current: P95 latency at 850ms (baseline: 250-300ms) **Evidence:** • Database query time increased from 50ms to 600ms average • Slow query: SELECT * FROM prices WHERE product_id IN (...) loading 500+ products • No recent deployments (last deploy: yesterday 3pm) ``` {% endcode %} **Your follow-up:** {% code overflow="wrap" %} ``` What's the typical query performance for pricing-api? ``` {% endcode %} **Cleric's response:** {% code overflow="wrap" %} ``` Baseline (last 7 days): 40-60ms P95 Current: 600ms+ P95 (10x degradation) Started after 2x traffic increase this morning. ``` {% endcode %} Cleric maintains context throughout the thread, so you can continue asking follow-up questions without repeating information. ### What Else Can You Do? For more investigation examples, see [Common Use Cases](/usage/common-use-cases), which includes 40+ example prompts for: * Incident investigation and debugging * Service health checks * Log and metric analysis * Proactive scans * Incident retrospectives * Knowledge retrieval ## Tips for Better Investigations ### Be Specific Include details to help Cleric scope the investigation: ❌ **Too vague:** ``` @Cleric Something is wrong ``` ✅ **Better:** ``` @Cleric Users are reporting 503 errors on the checkout page since 2pm EST. Check GCP logs and recent deployments. ``` ### Include Time Windows Specify when the issue started or what time range to examine: {% code overflow="wrap" %} ``` @Cleric Check error logs for the last 4 hours @Cleric What happened to the payments service between 2pm and 3pm PST? @Cleric Compare current memory usage to baseline from last week ``` {% endcode %} ### Request Evidence Ask for links to dashboards, logs, and metrics: {% code overflow="wrap" %} ``` @Cleric Check payments health and include evidence links @Cleric Show me which pods are using the most memory, with links to metrics ``` {% endcode %} ### Specify Data Sources Guide Cleric to specific integrations when needed: {% code overflow="wrap" %} ``` @Cleric Using Datadog, show me error logs for checkout-service @Cleric Check Prometheus metrics for CPU usage spikes @Cleric Search GCP logs for timeout errors ``` {% endcode %} ## Automatic Alert Investigation Instead of manually starting investigations, you can configure Cleric to automatically investigate alerts posted to Slack channels. See [Configuring Automations](/setup/agents-and-triggers) to set up automatic investigations based on keywords. ## Next Steps Now that you've run your first investigation: 1. **Teach Cleric about your environment** * Accept [Memory proposals](/learning/memories) to help Cleric learn * Configure [Global Guidance](/setup/providing-context) with preferences and context 2. **Automate investigations** * Invite Cleric to your alerts and incident channels * [Configure Agents and Triggers](/setup/agents-and-triggers) for automatic triage 3. **Explore advanced use cases** * See [Common Use Cases](/usage/common-use-cases) for investigation patterns * Learn how to use Cleric for retrospectives, proactive scans, and more 4. **Add more integrations** * Browse [Supported Integrations](/integrations/supported-integrations) * Connect additional observability tools and data sources ## Getting Help * **Support:** Contact or reach out via your dedicated Slack Connect channel # How Investigations Work How Cleric investigates, monitors, and resolves issues Before investigating a new production problem, Cleric creates an **issue** to track it. Issues can start from monitoring alerts, Slack messages, or web requests. Each issue keeps the full history: the original report, related alerts, Cleric's investigation, evidence, suggested fixes, follow-up conversation, monitoring checks, and final resolution. ## Issue Lifecycle Most issues move through this lifecycle: 1. **Issue creation**: Cleric receives an alert or user request. If the alert matches a recent related issue, Cleric groups it into that issue instead of creating a duplicate. 2. **Investigation**: Cleric gathers context, queries connected integrations, correlates evidence, and looks for a root cause. 3. **Outcome**: Cleric either suggests a fix or reports that the evidence is inconclusive. Cleric continues to monitor the problem in the background. 4. **Resolution**: The issue closes when the problem clears, a fix is verified, or Cleric determines that the alert was a false positive. ## Issue Creation An issue starts in one of the ways below. Alerts reach Cleric through Slack: there is no separate webhook to configure for PagerDuty, Datadog, Grafana, Alertmanager, or other alerting tools. ### From Alerts Alert-triggered issues start when a configured automation receives a matching alert in Slack. Send your alerting tool's notifications to a Slack channel, invite Cleric to that channel, and add a **Bot message** trigger for it (see [Configuring Automations](/setup/agents-and-triggers#triggers)). Cleric uses the alert text, source metadata, Slack channel, service names, labels, and links to understand what fired and whether it should create a new issue. Before creating a new issue, Cleric checks whether the alert belongs to a recent open issue. If it does, Cleric groups the alert into the existing issue instead of starting another. ### From Slack or the Web User-initiated issues start when you mention `@Cleric` in Slack or create a **New issue** in the web app. These issues are interactive: Cleric can ask follow-up questions, incorporate your answers, and continue investigating in the same thread or web chat. ### On a Schedule A **Scheduled** trigger runs an agent on a recurring schedule and posts the result to a Slack channel. See [Configuring Automations](/setup/agents-and-triggers#triggers). ### From Incident Channels Cleric can start an investigation in each incident channel it joins automatically. This is off by default. See [Incident Channels](/usage/collaborating-with-cleric#incident-channels). ### From Coding Agents Claude Code, Cursor, and other MCP clients can start an investigation with the `create_issue` tool. See [MCP Server](/integrations/mcp). ## Investigation Cleric investigates each issue systematically, but adapts as evidence emerges. ### Initial Assessment Cleric starts by identifying the problem scope: * Parse alert or request metadata, including severity, source system, labels, tags, and affected components * Identify likely services, environments, clusters, namespaces, or infrastructure resources * Determine whether the issue is alert-triggered or user-initiated * Look for related issues, recent alerts, and relevant historical context ### Evidence Gathering Cleric queries your connected integrations to gather relevant data. Depending on the issue, this can include metrics, logs, traces, deployments, Kubernetes resources, cloud resources, incident history, code changes, runbooks, and monitoring configuration. The investigation changes direction as evidence appears. If an alert initially looks like an infrastructure problem but logs point to a recent deployment, Cleric pivots toward application and release evidence. ### Correlation Cleric correlates data across systems to identify relationships that may not be obvious from a single dashboard or log stream: * Align events across monitoring systems, deploy history, logs, and infrastructure changes * Compare symptoms against baselines and known historical patterns * Connect application errors with resource pressure, configuration changes, dependency failures, or traffic shifts * Separate likely causes from coincidental events ### Results Cleric reports what it found with evidence, reasoning, uncertainty, and recommended next steps. The web issue page preserves the full activity log so you can inspect tool executions, intermediate findings, and conversation history. ## Issue Statuses Cleric exposes five issue statuses, listed below. Note that issues that only invoke custom agents may not enter certain states. | Status | What it means | What to do next | | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | | **Investigating** | Cleric is actively working, gathering evidence, or still running the investigation. | Wait for results, or interrupt the agent and provide additional context if desired. | | **Fix suggested** | Cleric found a likely root cause and proposed a remediation. The issue is still open until the fix is applied, verified, or otherwise resolved. | Review the suggested fix and apply it if appropriate. | | **Monitoring** | Cleric is watching an observable recovery signal before making a final resolution call, such as whether the alert clears or metrics return to normal. | Add missing context, grant access to missing data, or ask follow-up questions. | | **Inconclusive** | Cleric completed the investigation but could not identify a confident root cause or actionable fix from available evidence. | Add missing context, grant access to missing data, or ask follow-up questions. | | **Resolved** | The issue is closed because the problem cleared, a fix was verified, another fix resolved it, the issue self-resolved, or it was determined to be a false positive. A problem that keeps recurring is not resolved while its cause is still in place. | No action required. | ### Common Status Transitions Issues do not have to visit every status. Common paths include: * **Fix found**: `Investigating → Fix suggested → Resolved`. Cleric may monitor fix application or recovery in the background while the user-facing status remains **Fix suggested**. * **No clear root cause**: `Investigating → Inconclusive`. * **Observable recovery without a proposed fix**: `Investigating → Monitoring → Resolved`. **Monitoring** appears when the investigation has completed, there is no active proposed fix, and Cleric has scheduled an active resolution check that can observe whether the issue clears. * **Monitoring cannot confirm recovery**: `Investigating → Monitoring → Inconclusive`. This can happen when the scheduled check reports that the signal is no longer reliable, or when the observation window expires without enough evidence to mark the issue resolved. * **Resolved after monitoring ends**: `Fix suggested → Resolved` or `Inconclusive → Resolved`. Cleric watches an issue for 96 hours after its last activity (a follow-up to Cleric in the thread, or a new occurrence of the problem). After that, Cleric re-checks each open issue at most once a week, for up to 21 days after the last activity, and marks it resolved when the evidence shows the problem gone. Each re-check looks at the current state once and does not start a new monitoring window. Issues that are still open after 21 days keep their last status until you follow up in the thread or the problem recurs. * **False positive, self-resolved, or fixed via other means**: `Investigating → Resolved`. * **Problem recurs after it was resolved**: when a new alert is grouped onto a resolved issue, or a later occurrence is merged into it, Cleric reopens the issue immediately and reassesses it against every occurrence. It stays open while the cause of the recurrences is still in place. Issues resolved as false positives stay resolved, since the alert firing again is expected. ## When Cleric Needs More Information How Cleric handles missing information depends on how the issue started. ### User-Initiated Issues When you start an issue via `@Cleric` in Slack or the web app, Cleric can ask clarifying questions before continuing. This happens when: * **Scope is ambiguous**: The issue could apply to multiple services, environments, clusters, or time windows. * **Access is missing**: Cleric identifies a relevant data source it cannot reach. * **Evidence conflicts**: Cleric finds plausible explanations that require human context to prioritize. * **Operational context is unavailable**: Cleric needs information that is not present in connected tools, such as whether a deployment or load test was intentional. Reply in the same Slack thread or web chat. Cleric incorporates your answer and continues the issue. ### Alert-Triggered Issues When an alert triggers an issue automatically, Cleric does not usually ask questions before reporting findings. It investigates with available data and explicitly notes any gaps, missing access, or assumptions that could affect the conclusion. ## When Cleric Cannot Find a Root Cause Not every issue reaches a definitive root cause. When the evidence is insufficient, Cleric should make that uncertainty explicit instead of guessing. In inconclusive cases, Cleric reports: * **Partial findings**: Relevant logs, metric anomalies, configuration changes, or timeline details that may still help your team. * **Access limitations**: Data sources that could not be reached because of permissions, missing integrations, retention windows, or connectivity. * **Remaining uncertainty**: What Cleric could not prove and what additional information would help. You can continue the issue at any time by replying with more context, asking Cleric to check another source, or starting a deeper investigation from a specific hypothesis. ## Where to Inspect an Issue Use Slack for fast collaboration and the web app for the complete record. * **Slack thread**: See updates, answer questions, add context, and ask follow-ups where your team is already working. * **Web issue page**: Review status, grouped alerts, investigation history, evidence, suggested fixes, activity logs, and the complete conversation. # Collaborating with Cleric How to work with your new teammate Cleric works alongside your team in Slack and through the web interface. This guide explains the mechanics of how to interact with Cleric across different platforms. > **Looking for investigation examples?** See the [Quick Start Guide](/meet-cleric/quick-start) or [Common Use Cases](/usage/common-use-cases) for example prompts and workflows. ## Starting Investigations ### From Alerts (Automatic) Configure Cleric to automatically investigate specific alerts when they fire. See [Configuring Automations](/setup/agents-and-triggers) to set up triggers for your alert channels. When a new alert looks like the same problem as a recent issue in the same channel, Cleric attaches it to that issue instead of starting a new one. See [How Investigations Work](/usage/how-investigations-work#from-alerts). ### On-Demand (Slack) Start an investigation anytime by mentioning `@Cleric` in any channel where Cleric is present: 1. Type `@Cleric` followed by your question or issue description 2. Cleric responds with a 👀 emoji to acknowledge 3. Investigation results appear in a thread 4. Continue the conversation in the thread **Where to ask:** * Incident channels - during active issues * Team channels - for general questions * Alert channels - to supplement automatic investigations ### On-Demand (Web) From the Cleric web interface: 1. Navigate to `.app.cleric.ai` 2. Click **New issue** in the sidebar 3. Describe the issue or select an example prompt 4. Click send to start the investigation ### Deep Investigations with `!investigate` By default, on-demand investigations (from Slack or web) use a conversational mode that asks clarifying questions as it goes. If you want Cleric to run a full deep investigation instead, include `!investigate` in your message: ``` @Cleric !investigate checkout latency is spiking on the payments service ``` This triggers the same thorough investigation that alert-triggered issues receive, with extended analysis and evidence gathering. Works in both Slack and the web UI, including follow-up messages in an existing thread. The `/new` page shows example prompts for common scenarios like investigating errors, building incident timelines, or checking service health. Click any prompt to auto-fill the input and edit as needed. You can view investigation progress, reasoning, and tool execution in the web interface. ## Incident Channels Cleric can join your incident channels as soon as they're created, so nobody has to invite it mid-incident. This is off by default; turn it on if your team opens a public Slack channel per incident. ### Joining incident channels automatically 1. Open **Integrations** in the sidebar and select **Slack** 2. Under **Settings**, turn on **Join incident channels automatically** 3. If your incident channels don't start with `inc-`, change **Channel name prefix** and click **Save** The prefix is matched against the start of the channel name. Capitals and a leading `#` are ignored, and it can contain only letters, numbers, hyphens and underscores. Choose a prefix that only incident channels use: `inc` would also match `#incoming-leads`, while `inc-` would not. **Turn it on when:** * Your incident tool (or your team) creates a public channel per incident * Nothing in your incident process adds Cleric to those channels today **Leave it off when:** * Your incident workflow already invites `@Cleric` (for example, incident.io's **Invite a Slack bot user to an incident channel** step) and you don't want Cleric to investigate on its own. Cleric only starts investigations in channels it joined automatically, so to get them, switch from the workflow step to auto-join. * You only want Cleric in the incidents where someone asks for it. Invite it with `/invite @Cleric` in those channels. {% hint style="info" %} Slack doesn't let apps join private channels on their own, so auto-join only covers public incident channels. For private incident channels, add Cleric from your incident workflow or with `/invite @Cleric`. Auto-join also only applies to channels created after you turn it on; it doesn't join existing channels. {% endhint %} ### What Cleric does in an incident channel Cleric can start an investigation in each incident channel it joins automatically, without anyone having to ask. This is off by default. To turn it on, open **Integrations** → **Slack** and, under **Settings**, turn on **Join incident channels automatically** and then **Investigate new incident channels**. Only channels Cleric joined automatically are investigated. When someone invites Cleric, for example by mentioning it in a channel it isn't in, or adds it from the Slack integration page, Cleric joins without starting an investigation. Mention `@Cleric` to ask it something there as usual. For each channel it joins automatically: 1. Cleric waits a few seconds, so the incident's announcement, the channel topic and the first messages have been posted 2. It reads the channel's name, topic and purpose, and what has been said so far 3. It posts in the channel that it is investigating, and puts its progress and findings in the thread under that message Cleric starts one investigation per incident channel. Continue the conversation in Cleric's thread as you would for any investigation. In any channel whose name starts with your incident channel prefix, Cleric treats the whole channel as context, not only the thread it was asked in: it reads what has been posted across the channel before forming hypotheses or answering. ### Asking Cleric elsewhere in the channel You can also mention `@Cleric` in a new message or another thread of the incident channel. Cleric answers there, as a separate chat or issue, and it knows about the investigation it started for the channel: it reads that investigation's current hypotheses and latest update before answering, and tells you when what it finds disagrees with them. ### Finding incident work in the web app * On the **Issues** page, the investigation Cleric started for an incident channel has the source **Incident**. Filter by **Source** → **Incident** to see only those. * To see every issue from incident channels, including the ones people asked Cleric for there, filter by **Slack channel** → **All incident channels**. * An issue from an incident channel links to the investigation Cleric started for the channel under **Incident investigation** in its details. * It also shows how many other issues and chats came from the channel under **Incident threads**. Open it to see them. * A chat asked in an incident channel links to that investigation from its header, next to the channel name. To take Cleric out of an incident channel, run `/remove @Cleric` in the channel or remove it from the channel list on the Slack integration page. ## Continuing Investigations ### In Slack Threads Cleric maintains context throughout a thread, so you can continue the conversation naturally. When Cleric's most recent message is nearby in the thread, you can reply conversationally and Cleric will respond automatically. To always get a response, mention `@Cleric` in your reply. **What you can do in threads:** * Ask follow-up questions without repeating context * Request additional analysis or evidence * Ask Cleric to check earlier time windows * Verify that fixes resolved issues * Explore alternative hypotheses * Request deeper investigation into specific findings ### Contextual Responses Contextual responses allow Cleric to respond to thread replies without an explicit `@Cleric` mention. When you reply in a thread where Cleric recently sent a message, Cleric reads the conversation context and determines whether your reply expects a response. **When Cleric responds without a mention:** * Your reply is in a thread (not a top-level channel message) * Cleric sent a message recently in the thread (within the last few messages) * No other users have joined the conversation since Cleric's last message * Your message is not directed at another person (no `@user` mentions to non-Cleric users) * Contextual responses are not muted for the thread **When Cleric does not respond:** * Your message is a top-level channel message (not a thread reply) * Cleric's last message is too far back in the thread * Another user replied after Cleric, shifting the conversation away * Your message mentions another user * Your reply is an acknowledgment, thanks, or casual remark that does not need a response {% hint style="info" %} When in doubt, Cleric errs on the side of responding. If Cleric responds when you did not need it to, you can mute contextual responses for that thread. {% endhint %} ### Thread Commands Use these commands in any Slack thread where Cleric is active. Mention `@Cleric` followed by the command: | Command | What it does | | ---------------- | ------------------------------------------------------------------------------------------------- | | `@Cleric mute` | Turns off contextual responses for this thread. Cleric will only respond when directly mentioned. | | `@Cleric unmute` | Turns contextual responses back on for this thread. | | `@Cleric stop` | Interrupts the active investigation in this thread. | Cleric confirms each command with a checkmark emoji. If the command cannot be executed (for example, `stop` when no investigation is running), Cleric reacts with a failure emoji instead. {% hint style="info" %} Muting and unmuting apply per thread. Muting one thread does not affect other threads. {% endhint %} ### Scheduled Follow-ups You can ask Cleric to check back on an issue after a delay. This is useful when you've deployed a fix and want to verify it worked, or when you're waiting for a change to propagate. In any Slack thread or web chat, tell Cleric when to follow up: {% code overflow="wrap" %} ``` @Cleric check the error logs again in 30 minutes and see if the errors have stopped ``` {% endcode %} {% code overflow="wrap" %} ``` @Cleric follow up in an hour and let me know if the pod restarts again ``` {% endcode %} Cleric will wait the specified time, then run the requested check and report back in the same thread. You can continue using the thread normally in the meantime. Cleric is able to change or cancel a scheduled follow-up when requested. ### Via Web Interface From the Issue Details page (`.app.cleric.ai/issues/{id}`): 1. View full investigation history and reasoning 2. See all tool executions and evidence gathered 3. Continue the conversation in the chat interface 4. Share the investigation URL with team members The web interface provides more detailed visibility into Cleric's reasoning process and tool usage compared to Slack. ### Responding to Cleric's Questions For user-initiated investigations (started via `@Cleric` or the web app), Cleric may ask clarifying questions when it needs additional context to proceed, such as which environment to check or which service to prioritize. When this happens: 1. Reply in the same Slack thread or web chat 2. Cleric incorporates your answer and continues investigating For alert-triggered investigations, Cleric does not ask questions. It completes the investigation with available data and reports any gaps in its findings. ## Sharing Files with Cleric You can attach files directly to your Slack messages when working with Cleric. This is useful for sharing: * Log files or error outputs * Configuration files * Screenshots of dashboards or errors * Code snippets or stack traces Simply attach the file to your Slack message when mentioning Cleric. You can attach multiple files in a single message. Cleric will process all file contents alongside your message. {% hint style="info" %} File attachments are currently only supported in Slack. Adding and viewing attachments in the web interface is not yet available. {% endhint %} # Reviewing the Activity Log Understanding investigation history When Cleric investigates an issue, it maintains a detailed Activity Log that shows exactly what it did, what it found, and how it reached its conclusions. Reviewing this history helps you understand the investigation process, validate findings, and learn from Cleric's approach. ## Accessing the Activity Log **From Slack**: Click the "Open in Cleric" link in any Cleric response. **From Web**: 1. Navigate to `.app.cleric.ai` 2. Go to **Issues** to see all investigations 3. Click any issue to view its complete history ## Understanding the Activity Log The Activity Log shows Cleric's complete investigation process in chronological order: **Investigation Planning**: * Initial analysis of the problem * Task planning and prioritization * Investigation strategy decisions **Tool Executions**: * Which tools Cleric used * Specific commands and queries executed * Raw output from each tool **Analysis and Reasoning**: * How Cleric interpreted the data * Connections made between different evidence * Reasoning process for reaching conclusions **Plan Updates**: * How the investigation evolved based on findings * Changes in direction or focus * New tasks added based on discoveries ## Improving Future Investigations When you identify areas where investigations could be better, here's how to help Cleric improve: **Missing Context**: * **Problem**: Cleric missed important environmental factors (maintenance windows, known system quirks, business context) * **Solution**: Share this context with Cleric during the investigation. Cleric will offer to remember useful facts for future investigations. **Tool Gaps**: * **Problem**: Investigation failed because Cleric couldn't access needed data sources or got permission errors * **Solution**: Configure additional integration access or update credentials in **Integrations** **Pattern Recognition**: * **Problem**: Cleric didn't recognize recurring failure patterns specific to your environment * **Solution**: Tell Cleric about the pattern. Cleric will offer to remember this for future investigations. # Common Use Cases Ideas for how to use Cleric > **New to Cleric?** Start with the [Quick Start Guide](/meet-cleric/quick-start) to run your first investigation, then return here for more examples. This guide provides a comprehensive library of prompts showing various ways to use Cleric. In addition to automated alert triage, use Cleric to troubleshoot production issues, run proactive health scans, analyze observability data, or assist with incident retrospectives. ## Use Case Guides * [Change Verification](/usage/change-verification): Verify that a released change produced its intended outcome and did not cause regressions. ## Quick Tips * **Be specific**: Help Cleric scope its investigation by including details like time windows (and timezones!), identifiers, and resource names * **Describe the symptom**: Include what users are seeing and any error messages, and attach images when appropriate * **Ask for evidence**: Request links to dashboards, log queries, and traces and ask Cleric to cite its sources * **Follow up**: Ask for additional hypotheses, further investigation, and remediation proposals ## Example Investigation Flow Here's what a complete investigation looks like: {% code overflow="wrap" %} ``` @Cleric Users are reporting that checkout is failing intermittently since 2pm CET with 503s. Check the GCP logs and correlate with any recent deployments. ``` {% endcode %} **Cleric's response:** {% code overflow="wrap" %} ``` **Root Cause:** Database connection pool exhaustion in checkout-service **Timeline:** - 2:00 PM CET: Traffic increased 3.5x due to marketing campaign launch - 2:15 PM CET: Connection pool reached 100% utilization (10/10 connections) - 2:15 PM CET: First 503 errors appeared in logs **Evidence:** • GCP Logs show "waiting for available database connection" warnings • Connection pool metrics show sustained saturation since 2:15 PM (10/10 connections) • Error rate: 12% of checkout requests (847 failures / 7,058 requests) ``` {% endcode %} **Follow-up conversation:** {% code overflow="wrap" %} ``` What's the typical connection pool usage outside of incidents like this? ``` {% endcode %} {% code overflow="wrap" %} ``` Last 30 days: • Baseline: 4-6 connections (40-60% of pool) • Peak hours (9am-5pm CET): 7-8 connections (70-80%) • Off-hours: 2-3 connections (20-30%) Today: 10/10 sustained (100% utilization, unusual) ``` {% endcode %} ## Customizing Your Prompts You can modify any prompt by specifying: | Dimension | Examples | | ----------------- | ----------------------------------------------------------------------- | | **Data source** | "using Prometheus...", "check Datadog for...", "search GCP logs for..." | | **Scope** | "for checkout-api", "in the UAT environment", "in the us-west region" | | **Time window** | "in the last 4 hours", "since 2pm PST", "between Jan 15 2-4pm UTC" | | **Output format** | "with evidence links", "as a timeline", "summarize in bullet points" | ## Investigate Issues Understand what's happening when something goes wrong. ### Incident/bug investigation {% hint style="info" %} Prefix any prompt with `!investigate` to trigger a full deep investigation instead of conversational mode. See [Deep Investigations](/usage/collaborating-with-cleric#deep-investigations-with-investigate). {% endhint %} {% code overflow="wrap" %} ``` Users are reporting that checkout is failing intermittently since 2pm CET with 503s. Check the GCP logs and correlate with any recent deployments. ``` {% endcode %} {% code overflow="wrap" %} ``` Look for logs in the last 24h related to app installations in the canary instance and tell me if you see anything indicating a failure. The user reports seeing an error about a missing field. ``` {% endcode %} ### Service health {% code overflow="wrap" %} ``` Check payments health since 9am PST, include evidence links. ``` {% endcode %}
Example response {% code overflow="wrap" %} ``` Payments service health check (since 9:00 AM PST): **Status:** ✅ Healthy **Metrics:** • Uptime: 100% (no restarts or crashes) • Error rate: 0.08% (3 errors / 3,847 requests) - within normal range • P95 latency: 245ms (baseline: 220-250ms) • Memory usage: 1.2GB / 2.0GB (60% - normal) **Recent Activity:** • No deployments since yesterday 3:15 PM PST • Traffic volume: 15% above baseline (expected for Monday morning) **Alerts:** None active **Evidence:** [Datadog dashboard →] | [Error logs →] | [Metrics →] Everything looks healthy. The 3 errors were timeout exceptions from the external payment gateway (Stripe) and were automatically retried successfully. ``` {% endcode %}
{% code overflow="wrap" %} ``` Are there any open heartbeat alerts for the marketing site? ``` {% endcode %} ### Debugging errors {% code overflow="wrap" %} ``` Debug why Prometheus in the platform cluster has unhealthy ingesters since 10am EST ``` {% endcode %}
Example response {% code overflow="wrap" %} ``` **Root Cause:** Disk space exhaustion on ingester nodes **Timeline:** • 9:45 AM EST: Disk usage reached 95% on ingester-2 and ingester-3 • 10:00 AM EST: Ingesters marked as unhealthy by Prometheus • 10:15 AM EST: Write requests began failing with "insufficient disk space" errors **Impact:** • Write path degraded: 40% of metrics samples dropped • Read path operational: Query performance unaffected • Data loss: ~2 hours of metrics for affected series • Node count: 3 ingesters, 2 unhealthy **Evidence:** • Ingester logs show "no space left on device" errors, disk at 98% utilization • WAL segment size increased 300% in last 7 days due to high cardinality metrics ``` {% endcode %}
{% code overflow="wrap" %} ``` Debug why the KEDA autoscaler has been throwing errors for the last 4 hours ``` {% endcode %} ### Logs & metrics analysis {% code overflow="wrap" %} ``` Using GCP logs, get the most common errors across all our customers in the last day. ``` {% endcode %} {% code overflow="wrap" %} ``` Search Datadog logs for any errors related to user 3bc96ec9-9367-4e40-8673-6a2fc9ceb87b ``` {% endcode %} {% code overflow="wrap" %} ``` Check the last 7 days of error logs for the acme instance. Group the logs into top 3 error patterns with counts and first/last seen and print it as a markdown table. ``` {% endcode %}
Example response {% code overflow="wrap" %} ``` Top 3 error patterns (last 7 days): | Error Pattern | Count | First Seen | Last Seen | Severity | |--------------|-------|------------|-----------|----------| | `ConnectionPoolTimeoutException: Could not acquire connection from pool` | 1,247 | Jan 23, 08:15 AM | Jan 29, 11:42 PM | ERROR | | `ValidationError: Missing required field 'customer_id' in request` | 892 | Jan 24, 02:30 PM | Jan 30, 09:15 AM | ERROR | | `HTTPException: 503 Service Unavailable from pricing-api` | 456 | Jan 26, 10:00 AM | Jan 29, 06:30 PM | ERROR | **Analysis:** • Connection pool errors: steady increase (avg 178/day) • Validation errors: spiked Jan 27 (402 occurrences), then decreased • 503 errors from pricing-api: intermittent, clustered around peak hours ``` {% endcode %}
{% code overflow="wrap" %} ``` Show the top 10 services with highest error rate increase vs baseline since midnight ``` {% endcode %} ### CI/CD failures {% code overflow="wrap" %} ``` Investigate why the last 3 web-app pipeline runs failed at the same post-deploy step waiting for the new version to come up. ``` {% endcode %} ## Proactive Scans Run fleet-wide scans to catch issues before they become incidents, or to improve observability data hygiene. ### Warning spike scan {% code overflow="wrap" %} ``` Run a proactive system health check. Find services with a spike in WARNING logs as compared to baseline. List the warning patterns and whether they correlate with any recent deploys. ``` {% endcode %}
Example response {% code overflow="wrap" %} ``` 3 services with elevated WARNING logs: **1. inventory-api** (+245% vs baseline) • Warning pattern: "Cache miss rate above threshold: 45%" • Baseline: 12 warnings/hour → Current: 41 warnings/hour • Correlation: Deployed v2.8.0 on Jan 28 at 2pm (Redis cache configuration changed) **2. notification-service** (+180% vs baseline) • Warning pattern: "Retry queue depth exceeds 1000 messages" • Baseline: 5 warnings/hour → Current: 14 warnings/hour • Correlation: No recent deployments (last deploy: Jan 20) **3. analytics-service** (+120% vs baseline) • Warning pattern: "Query execution time exceeded 5s threshold" • Baseline: 8 warnings/hour → Current: 18 warnings/hour • Correlation: No deployments, data volume increased 3x on Jan 27 **Summary:** • 1 of 3 spikes correlates with deployment • 2 spikes related to external factors (email service, data volume) • No critical issues detected ``` {% endcode %}
### Log clean up {% code overflow="wrap" %} ``` Identify the top 5 services that produced the most logs over the last 7 days. Propose recommendations of changes we can make to reduce log volumes. ``` {% endcode %} ## Incident Retrospectives Get help answering retrospective questions or building post-incident timelines. ### Structured retrospective {% code overflow="wrap" %} ``` Use the attached conversation log to produce a structured retrospective report. Establish start time and mitigation time, build an evidence-based timeline, and identify contributing factors. Include evidence links. ``` {% endcode %} ### Timeline construction {% code overflow="wrap" %} ``` Help me build a timeline for the incident yesterday between 2pm and 4pm PST. ``` {% endcode %}
Example response {% code overflow="wrap" %} ``` **Incident Timeline: Jan 29, 2pm - 4pm PST** **14:00 - Detection** • PagerDuty alert: "High API Error Rate - checkout-service" [Alert →] • User reports begin in #support channel (5 reports of checkout failures) **14:05 - Initial Response** • On-call engineer acknowledges alert • Error rate: 15% (baseline: <0.5%) • P95 latency: 3.2s (baseline: 450ms) **14:12 - Investigation Begins** • Checkout-service logs show database connection timeouts • Connection pool: 30/30 connections in use (100% utilization) • No recent deployments to checkout-service **14:18 - Root Cause Identified** • Database primary experiencing high CPU (95% utilization) • Slow query detected: Complex JOIN query from analytics-service • Query running since 13:58 (14 minutes before incident) **14:25 - Mitigation Started** • Analytics team contacted • Long-running query killed on database primary • Connection pool begins recovering **14:32 - Service Recovery** • Error rate drops to 2% • Latency returns to baseline (480ms) • Connection pool utilization: 45% **14:45 - Full Resolution** • Error rate: <0.5% (normal) • All services healthy • User reports cease **15:30 - Post-Incident Actions** • Query timeout added to analytics-service (30s limit) • Database query monitoring alerts configured • Incident review scheduled for Jan 31 **Duration:** 45 minutes (detection to resolution) **Impact:** ~15% of checkout transactions failed during incident window ``` {% endcode %}
{% code overflow="wrap" %} ``` What were the contributing factors to the web-app outage last Tuesday? ``` {% endcode %} ## Retrieve Knowledge Query your documentation, your codebase, or Cleric's knowledge. ### Documentation lookups {% code overflow="wrap" %} ``` What does our GitOps Runbook say about the debugging flow? ``` {% endcode %} {% code overflow="wrap" %} ``` Search Confluence for the on-call escalation process. ``` {% endcode %} ### Codebase exploration {% code overflow="wrap" %} ``` Investigate under what circumstances a `user_created` event would be tagged with `source` of "system unknown" ``` {% endcode %} ### Issue/tenant lookup {% code overflow="wrap" %} ``` What tenant does issue_id 4c4d742c-2532-4941-8106-7ba112b7fa92 belong to? ``` {% endcode %} ### Tool capabilities {% code overflow="wrap" %} ``` Which clusters are visible to you when using the datasource 'logs-nonprod'? ``` {% endcode %} {% code overflow="wrap" %} ``` What can you do with your AWS credentials? ``` {% endcode %} ### Memory queries {% code overflow="wrap" %} ``` Search your memories for how to identify a tenant from a user id. ``` {% endcode %} {% code overflow="wrap" %} ``` What do you know about the payments service? ``` {% endcode %}
Example response {% code overflow="wrap" %} ``` Here's what I remember about the payments service: **Service Details:** • Owner: Payments team (#payments-oncall for escalations) • Primary dependencies: Stripe API, inventory-api, pricing-api • Database: Uses payments_db with read replicas in us-east and us-west **Known Behaviors:** • Memory usage spikes to ~2.5GB during month-end batch processing (expected behavior) • Read replica lag >500ms triggers automatic fallback to primary database • Timeout threshold for Stripe API calls: 10 seconds **Troubleshooting Guidance:** • When investigating latency: Check read replicas first, then Stripe API status • When investigating errors: 90% of payment failures are due to external gateway issues, not our service • Recent deployments: Always check if inventory-api was also deployed (frequent cause of integration issues) ``` {% endcode %}
## Remediate & Handoff Take action on issues: summarize findings, create tickets, or open pull requests. On the web issue page, use **More actions** on a suggested fix to open a prepared prompt in Claude Code, Codex, Conductor, or Cursor, or choose **Copy to clipboard**. The prompt includes the fix and investigation context. Select the intended repository in your coding agent before applying the fix. With GitHub or Bitbucket connected, choose **Create PR** to have Cleric implement the suggested fix and open a pull request for review. ### Summarization {% code overflow="wrap" %} ``` Generate a detailed summary of this issue, including a mermaid dataflow diagram of the current implementation. ``` {% endcode %} ### Investigation diagram {% code overflow="wrap" %} ``` Create a mermaid diagram representing the path of your investigation. If existing, dead-ends should be represented and the main "golden" path (from alert to conclusion) should be prominent. ``` {% endcode %} ### Create tickets {% code overflow="wrap" %} ``` Create a GitHub issue that summarizes the problem and potential solutions. Create a Jira ticket in project SRE with the root cause and remediation steps. ``` {% endcode %} ### Open pull requests {% code overflow="wrap" %} ``` Add debug logs to this flow and create a draft PR for me to review. ``` {% endcode %} ## Monitoring Production Keep an eye on production systems and verify changes are working as expected. ### Verify a fix {% code overflow="wrap" %} ``` The memory leak fix for auth-service was deployed at 3pm. Compare memory usage before and after the deploy. ``` {% endcode %} {% code overflow="wrap" %} ``` We rolled back the payments-api to the previous version. Verify that the 500 errors have stopped. ``` {% endcode %} ### Scheduled follow-ups Ask Cleric to check back after a delay. This is useful when you've pushed a fix and want to verify it later without watching dashboards yourself. {% code overflow="wrap" %} ``` I just deployed a fix for the connection pool issue. Check the error rate for checkout-service in 30 minutes and let me know if it's back to normal. ``` {% endcode %} {% code overflow="wrap" %} ``` Check the error logs for payments-api again in an hour and tell me if the timeout errors have stopped since the deploy at 2pm. ``` {% endcode %} # Change Verification Verify whether a released change worked and whether it caused regressions Change Verification verifies a released code or configuration change against production evidence. Cleric checks whether the intended outcome occurred, looks for regressions, and continues monitoring signals that need more time. ## How It Works Automatic verification begins when a configured Slack release notification runs the `verify` agent. For each release, Cleric: 1. Identifies what shipped, where and when it shipped, and whether the expected version is live. 2. Records each change. Cleric skips changes without a production outcome to verify. For every tracked change, it reads the source diff and records expectations about the running system. 3. Checks each expectation against production logs, metrics, traces, infrastructure state, or live configuration. It resolves the expectation when the evidence is sufficient or monitors it with a scheduled check when more observation time is needed. 4. Updates the change and expectation statuses as new evidence arrives. When a release contains several changes, Cleric assesses each change independently. This keeps an anomaly or missing data for one change from obscuring the results for the others. ## Baseline Assumptions Automatic Change Verification assumes that your environment has: * **Release notifications:** A Slack channel where a bot posts the deployed service or component, environment, rollout time, and version. Pull request or commit links improve the analysis. * **Source access:** A connected source-control integration that lets Cleric read change descriptions and diffs. * **Production access:** Connected integrations that expose the logs, metrics, traces, infrastructure state, or live configuration needed to assess the change. Cleric reports missing access or missing telemetry as a limitation. It does not treat an empty query result as proof until it has validated the query and its filters. ## Set Up Automatic Change Verification {% stepper %} {% step %} ### Prepare the Release Channel Choose the Slack channel that receives release notifications. A channel dedicated to deployments works best because a catch-all trigger can process every bot message without matching unrelated alerts. Invite Cleric to the channel with `/invite @Cleric` if it is not already a member. {% endstep %} {% step %} ### Add a Bot Message Trigger Open **Settings > Automations > Triggers** and click **Add trigger**. Keep the **Bot message** trigger type selected, then configure: * **Channel:** Select the release channel. * **And matches keyword(s):** Use `*` when every bot message in the channel is a release notification. Otherwise use a distinctive phrase that appears in release messages, such as `deployment completed`. * **Then > Run agent:** Select `verify`. Place this trigger above broader triggers that could match the same release message. The first matching trigger runs. {% endstep %} {% step %} ### Validate the Next Release After the next release notification, confirm that Cleric reacts to the message and posts a link in its thread. The link opens the **Changes** page scoped to that release. Confirm that Cleric identified the correct changes, target environment, and rollout time. {% endstep %} {% endstepper %} For more detail about trigger matching and ordering, see [Configuring Automations](/setup/agents-and-triggers#adding-a-bot-message-trigger). ## Run Change Verification From Slack Run the built-in agent from Slack by prefixing the request with `!verify`. Change verification cannot be started from web chat. For a pull request: {% code overflow="wrap" %} ``` @Cleric !verify https://github.com/acme/checkout/pull/1234 ``` {% endcode %} For another type of release, describe the change and target environment: {% code overflow="wrap" %} ``` @Cleric !verify Verify the checkout-api feature flag rollout in production from 14:00 UTC. ``` {% endcode %} If Cleric cannot identify the change or environment from the request and connected systems, it asks for the missing detail. # Setting Up with a Coding Agent Let Claude Code, Codex, Cursor or another coding agent set Cleric up over Cleric's MCP server If you're automating your production work with agents, it's only fair if you can automate all of Cleric's setup with agents too! You can use your coding agent to set Cleric up for you via MCP. Use it to figure out what infrastructure and observability tools to connect, route your alert and release channels to Cleric, and help you test everything with a first investigation. ## Get Started 1. Open **System Health** in Cleric and pick your agent under **Set up Cleric with your coding agent**: Claude Code, Codex, Cursor or Other. Any agent that can connect to an MCP server over HTTP works. 2. Run the commands it shows from within your main code repository, the one that describes where your services run. They include your API key, which Cleric shows only once. 3. Start setup with the prompt it shows. In Claude Code, that's `/mcp__cleric__onboard`. ## What to Expect Some steps like Slack and GitHub connections require you, so those come first. Your agent gives you a link to approve each one. Your agent will search your repository for the tools your team uses and show you one table: each tool, where it was found, whether Cleric supports it, and whether it is connected. You decide which ones to connect to Cleric. Cleric only gets read-only access. If your infrastructure is code, the agent opens a pull request for you to review. Once something is connected, it asks Cleric about one of your services and shows you the answer. ## What to Know * **It asks first.** Your agent will check with you before it creates a role, key or trigger, or changes how Cleric joins incident channels. * **Keys you paste will go to your agent's model provider.** You can enter them under **Integrations** in Cleric instead if you don't want this. * **It acts as you.** Your API key ends up in your agent's config and your shell history, and Cleric records what the agent does under your name. * **Don't see the section?** It shows only until Cleric finishes calibrating, and only where agent-led setup is turned on. Ask Cleric support, or connect your agent as the [MCP Server](/integrations/mcp) page describes. # Setting up SSO Configure Single Sign-On (SSO) for your organization {% hint style="info" %} By default, Cleric uses Third Party Sign In with Google. If your organization uses Google Workspace, no additional configuration is needed. {% endhint %} Cleric supports Single Sign-On via SAML or OIDC with most major Identity Providers, including: * Okta * Entra ID (formerly Azure AD) * Google Workspace * OneLogin * JumpCloud * PingOne / PingFederate ## Setup Process 1. We'll provide you with the **ACS URL** and **Entity ID** values for your organization. 2. Create a new SAML or OIDC application in your IdP's admin dashboard using the values we provided. 3. [Configure attribute mapping](#configure-attribute-mapping) in your IdP. 4. [Assign users and groups](#role-assignment) to the application in your IdP. 5. Share the **metadata** object (or metadata URL) from your IdP configuration back to us. 6. Once we receive your metadata, we'll finalize the SSO setup and confirm when it's ready. Don't see your Identity Provider listed? Cleric supports [many additional integrations](https://workos.com/docs/integrations). ## Configure Attribute Mapping Your Identity Provider must send the following four attributes in the SAML assertion. All four are required for Cleric to authenticate and identify users. | Attribute Name | Required | Description | | -------------- | -------- | --------------------------------------------- | | `email` | Yes | The user's email address | | `firstName` | Yes | The user's first name | | `lastName` | Yes | The user's last name | | `idpId` | Yes | A unique, stable user identifier from the IdP | How you configure these depends on your Identity Provider: {% tabs %} {% tab title="Okta" %} In the **Attribute Statements** section of your SAML application: 1. Add each attribute name exactly as shown in the table above (e.g., `email`, `firstName`). 2. Set the corresponding value to the appropriate Okta user profile field (e.g., `user.email`, `user.firstName`, `user.lastName`). 3. For `idpId`, map it to a stable unique identifier such as `user.id`. 4. Preview the SAML Assertion to confirm all four attributes are present before saving. {% endtab %} {% tab title="Entra ID" %} In your Enterprise Application's **Single sign-on** settings, under **Attributes & Claims**: 1. Edit the existing claims or add new ones so that each of the four attribute names above is present. 2. Map each claim to the corresponding Entra ID user attribute (e.g., `user.mail`, `user.givenname`, `user.surname`). 3. For `idpId`, map it to a stable unique identifier such as `user.objectid`. 4. If your IdP requires a namespace, ensure the claim name still resolves to the attribute names listed above. {% endtab %} {% tab title="Google Workspace" %} In the **Attribute Mapping** section of your SAML app configuration: 1. Add each attribute name exactly as shown in the table above. 2. Map them to the corresponding Google directory attributes (e.g., `Primary email`, `First name`, `Last name`). 3. For `idpId`, map it to a stable unique identifier. Note that Google SAML does not provide a built-in option to map a user's `id` attribute claim. Contact us if you need guidance on choosing the right value. {% endtab %} {% tab title="Other IdPs" %} Refer to your IdP's documentation for configuring SAML attribute statements. Ensure the four attribute names above are included in the assertion with the correct user profile mappings. {% endtab %} {% endtabs %} ## Role Assignment Assign users and groups in your Identity Provider so that the right people can access Cleric. At minimum, ensure that the engineering teams using Cleric are assigned to the application. {% tabs %} {% tab title="Okta" %} 1. In your SAML application, go to the **Assignments** tab. 2. Select **Assign to People** or **Assign to Groups**. 3. Find the relevant engineering teams or individual users and click **Assign** next to each. 4. Click **Done** when finished. {% endtab %} {% tab title="Entra ID" %} 1. In your Enterprise Application, go to **Users and groups**. 2. Click **Add user/group**. 3. Select the engineering teams or security groups that should have access to Cleric. 4. Click **Assign** to confirm. {% endtab %} {% tab title="Google Workspace" %} 1. In your SAML app settings, go to **User access**. 2. Enable the service for the relevant organizational units (OUs) that include your engineering teams. 3. Click **Save**. {% endtab %} {% tab title="Other IdPs" %} Refer to your IdP's documentation for assigning users or groups to a SAML application. Ensure the teams that will use Cleric are included. {% endtab %} {% endtabs %} # Configuring Automations Configure the workflows Cleric runs and how alerts are routed to them An **agent** is a named workflow with custom instructions that Cleric runs against an issue. A **trigger** is a rule that runs an agent automatically when a matching event fires. Cleric supports two trigger types: **Bot message**, which fires when a bot message posted in a Slack channel matches the trigger's keywords, and **Scheduled**, which fires on a recurring cron schedule. Triggers are one of several ways an issue starts. See [Issue Creation](/usage/how-investigations-work#issue-creation) for the full list. {% hint style="info" %} **Existing customers:** Triggers replace the prior "alert responses" configuration. Existing keyword routing was migrated automatically to triggers that point at the built-in `investigate` agent. No action is required to preserve previous behavior. {% endhint %} ## Agents ### Built-in The built-in `investigate` agent runs Cleric's deep root-cause analysis, exploring widely, forming hypotheses, and prioritizing accuracy over speed. It runs by default on alert-driven issues. On user-initiated issues, it runs when the message includes `!investigate` or natural-language investigation phrasing such as "investigate", "diagnose", "debug", "root cause", "look into", or "dig into". The `investigate` agent cannot be edited or deleted. ### Custom agents A custom agent has two fields: * **Name**: lowercase letters, numbers, and hyphens (e.g. `checkout-incident`, `db-failover`). Must start and end with an alphanumeric character, max 50 characters. Cannot collide with reserved names (e.g. `investigate`). * **Instructions**: free-text prompt that runs alongside Cleric's instructions when this agent fires. Custom agents let you apply Cleric to workflows beyond the default investigation. Use them for a lighter-weight response to events like deployment failures or to run a tailored workflow outside of a deep investigation. #### Example: Assess a pipeline failure **Name**: `pipeline` **Instructions**: ``` Your role is to determine why the pipeline job failed. 1. Retrieve the link to the failing job and check the GitHub Actions workflow logs. 2. Review the corresponding commit. 3. Determine: is the failing check a result of the commit, a previous commit (i.e. the same job failed in the previous workflow as well), or a transient failure? List your recommendation for how to proceed. ``` #### Example: Monitor a feature rollout **Name**: `monitor` **Instructions**: ``` Review the PR or commit that triggered the given GitHub Actions pipeline so you understand the context. Check the status of the pipeline. If it's still in progress, schedule a follow-up to check again in 5 minutes. If the pipeline completed successfully and non-trivial changes were rolled out, schedule a follow-up in 1-2 hours to verify the changes are working as expected. ``` ### Running an agent Agents run in two ways: **From a trigger (automatic).** When a **Bot message** trigger matches an incoming bot message, or when a **Scheduled** trigger's time elapses, Cleric runs the trigger's agent. See [Triggers](#triggers) below. **On-demand with `!agent-name`.** In any Slack thread or web chat, prefix your message with `!` followed by the agent's name to run that agent on the issue: ``` @Cleric !monitor the rollout of PR#1234. ``` `!agent-name` works in a new chat or as a follow-up in an existing thread. ### Managing agents {% stepper %} {% step %} #### Open Settings > Automations > Agents In the Cleric web app, open **Settings** from the sidebar, expand **Automations**, and select **Agents**. {% endstep %} {% step %} #### Create a new agent Click **New agent**. Give it a name and write instructions. The form validates the name format and rejects names already taken by another agent. {% endstep %} {% step %} #### Save Click **Save**. The agent is now available to run on demand via `!agent-name` and to attach to a trigger. Use the **Run agent** button in **Settings > Automations > Agents** to launch a new chat with `!` pre-filled. {% endstep %} {% step %} #### (Optional) Wire a trigger If you want the agent to run automatically, open **Settings > Automations > Triggers** and add a trigger: a **Bot message** trigger to run on matching bot messages, or a **Scheduled** trigger to run on a recurring schedule. {% endstep %} {% endstepper %} ### Limitations * Built-in agents cannot be edited, renamed, or deleted. * Custom agent names must be unique. * Deleting a custom agent also deletes any triggers that route to it. * Editing an agent's instructions takes effect on its next run. Follow-up messages in an existing thread also pick up the updated instructions. ## Triggers A trigger runs an agent automatically when a matching event fires. Each trigger has a type that determines the event it listens for: * **Bot message**: fires when a bot message posted in a Slack channel matches the trigger's keywords. Cleric runs the selected agent and replies in the thread. * **Scheduled**: fires on a recurring cron schedule. Cleric posts the result to the configured Slack channel. ### How a trigger fires When a bot posts a message in a channel with one or more **Bot message** triggers: 1. Cleric evaluates triggers in their listed order (top-down) for that channel. 2. For each trigger: if the message matches at least one keyword and doesn't match any of the trigger's exceptions, the trigger fires. The first match wins. 3. Cleric reacts with :eyes: on the message. 4. Cleric runs the trigger's agent on the resulting issue and posts a "Follow my progress" link in the thread. 5. When the agent completes, Cleric posts the result and updates the reaction to :white\_check\_mark: (success) or :warning: (failure). If no trigger matches, Cleric ignores the message. `@Cleric` mentions are not subject to triggers. They always create an issue regardless of channel configuration (see [Collaborating with Cleric](/usage/collaborating-with-cleric)). If the message matches a recent issue in the same channel, Cleric attaches it to that issue instead of running the agent again. See [How Investigations Work](/usage/how-investigations-work#from-alerts). ### Keyword matching Each trigger requires at least one keyword. The trigger fires when the message text contains any of its keywords. Use `*` to match all bot messages. Exceptions are optional; if the message matches any exception, the trigger does not fire even when a keyword matches. Use exceptions to suppress test alerts, staging environments, or resolution notifications. Keywords match as **case-insensitive substrings**. | Keyword | Matches | | ----------- | ------------------------------------------------------------------------------------ | | `error` | Any message containing "error" (e.g., "error occurred", "critical\_error", "errors") | | `OOMKilled` | Any message containing "oomkilled" (case-insensitive) | `*` is a wildcard that lets you require terms in a specific order: | Keyword | Matches | | ------------ | ------------------------------------------------------------------------------------- | | `*` | Every bot message in the channel (useful when the channel is high-signal) | | `error*rate` | Text where "error" appears before "rate" (e.g., "error\_rate", "error rate exceeded") | | `pod*crash` | Text where "pod" appears before "crash" (e.g., "pod xyz crashed", "pod-abc-crash") | {% hint style="info" %} Since keywords already match as substrings, `error` and `*error*` behave the same way. Use wildcards when you need to match multiple terms in a specific order (e.g. `pod*crash`), or to fire on every bot message in a channel (`*`). {% endhint %} ### Trigger order Within a channel, triggers evaluate top-down and the **first match wins**. Order matters when the same message could match more than one trigger. This typically happens when a specific trigger and a wildcard (`*`) route to different agents. When a channel has more than one trigger defined, drag the handle to reorder them. Put more specific triggers above broader ones. Reordering is disabled while any filters are applied so the visible order matches the actual evaluation order. ### Validation Cleric blocks two types of misconfiguration when you save a trigger: * **Duplicate**: a trigger already exists in this channel for the selected agent. The dialog links you to the existing one so you can edit it instead. * **Conflict**: another trigger in this channel matches the same messages and routes them to a different agent. This happens when: * Two triggers have the **same keywords** (or both are catch-all) and route to different agents. The first trigger always wins, so the second would never fire. * Two non-catch-all triggers **share at least one keyword** and route to different agents. Cleric can't determine which should run when a message matches both. A catch-all trigger combined with more specific triggers routing to different agents is allowed. Place the specific triggers above the catch-all so they match first, leaving unmatched messages for the catch-all. ### Adding a Bot message trigger {% stepper %} {% step %} #### Open Settings > Automations > Triggers In the Cleric web app, open **Settings** from the sidebar, expand **Automations**, and select **Triggers**. {% endstep %} {% step %} #### Add Cleric to the channel (if needed) In Slack, use `/invite @Cleric` to invite Cleric to the channel. Once Cleric is a member, the channel becomes selectable in the trigger dialog. {% endstep %} {% step %} #### Add a trigger Click **Add trigger**. In the **When** section, keep the **Bot message** type selected, then configure: * **Channel**: select the Slack channel. * **And matches keyword(s)**: enter keywords that fire the trigger (comma-separated). Optionally add **Except for** keywords to suppress matches. * **Then** → **Run agent**: select the agent to run. The Preview block at the bottom updates as you edit and shows the rule in plain English (e.g., *When a bot posts in #alerts-prod, matching "P0" or "Sev1", except "staging", run the **investigate** agent.*). {% endstep %} {% step %} #### Save Click **Add trigger**. Validation errors (duplicate or conflict) appear inline with a link to the conflicting trigger. The trigger takes effect immediately. {% endstep %} {% step %} #### (Optional) Order triggers within a channel If a channel has more than one trigger, drag triggers into the order you want them evaluated. Put specific triggers (e.g. matching a specific keyword) above generic triggers (e.g. catch-all `*`). {% endstep %} {% endstepper %} ### Scheduled triggers A **Scheduled** trigger runs an agent on a recurring schedule and posts the result to a Slack channel. Unlike **Bot message** triggers, Scheduled triggers don't react to channel messages: they fire on the schedule you set, regardless of channel activity. The trigger dialog offers five repeat presets: * **Every hour**: fires once per hour, on the minute you set. * **Every day**: fires daily at the time you set. * **Every weekday**: fires Monday through Friday at the time you set. * **Every week**: fires on the days of the week you select, at the time you set. * **Every month**: fires on the day of the month you select (1-28), at the time you set. Times use a 24-hour clock (for example, `14:30` is 2:30 PM). The schedule honors the timezone you select and adjusts for daylight saving transitions in that zone. Monthly schedules are capped at day 28 so the trigger fires consistently in every month. ### Adding a Scheduled trigger {% stepper %} {% step %} #### Open the trigger dialog In the Cleric web app, open **Settings** from the sidebar, expand **Automations**, select **Triggers**, and click **Add trigger**. {% endstep %} {% step %} #### Select the Scheduled type In the **When** section, switch from **Bot message** to **Scheduled**. {% endstep %} {% step %} #### Set the cadence Select a **Repeat** preset and the **At** time. For **Every week**, also select the days of the week. For **Every month**, also select the day of the month. Select a **Timezone**. {% endstep %} {% step %} #### Select the agent and destination Under **Then**, select the **Run agent** to invoke and the **Post results to** Slack channel where Cleric should send the output. {% endstep %} {% step %} #### Save The **Preview** at the bottom reads the schedule back in plain English (e.g. *Every weekday at 9:00 AM (America/Los\_Angeles), run the **investigate** agent and post to #alerts-prod.*) and shows the next run time. Click **Add trigger**. {% endstep %} {% endstepper %} To edit or delete a Scheduled trigger, click its row in **Settings > Automations > Triggers**. ## On-demand investigations Triggers control what runs **automatically** on bot messages. They do not affect `@Cleric` mentions or web-app investigations. You can always: * Mention `@Cleric` in any channel where Cleric is present to start an on-demand investigation. * Prefix your message with `!agent-name` to run a specific agent on demand. # Providing Context Provide documentation to improve investigations Cleric can access documentation from multiple sources to understand your system architecture, operational procedures, and environment-specific context. Cleric references this context when planning investigations and interpreting results. ## Documentation via Integrations Cleric can search and retrieve documentation during investigations using the [Atlassian](/integrations/supported-integrations#atlassian) and [GitHub](/integrations/supported-integrations#github) integrations. Combined with [Memories](/learning/memories) that Cleric learns from your conversations, documentation integrations are a meaningful way to set up Cleric with a comprehensive understanding of your environment. ## Global Guidance Global Guidance lets you provide preferences and context that apply to all investigations. Configure this from **Settings** in your Cleric dashboard. Write guidance in plain text. Be direct and specific. Cleric references this context when planning and conducting investigations. Use Global Guidance for preferences and tribal knowledge that isn't captured in Memories: ``` Always check for recent deployments first when investigating performance issues. When investigating database issues, check the read replicas before the primary. The checkout service depends on inventory-api and pricing-api. If checkout is slow, check those services first. Our staging environment uses the naming pattern *-staging. The payments-api service is owned by the payments team (#payments-oncall). ``` # Overview Connect Cleric to your infrastructure Cleric uses standard CLIs and APIs (`kubectl`, `gh`, `aws`, etc.) to query your infrastructure. An **Integration** is a credential configuration that authenticates Cleric with a specific system. You provide credentials once (API keys, tokens, service accounts), and Cleric uses them for all investigations. Most integrations require read-only access, though for some we suggest certain write permissions for enhanced functionality. ## Supported Capabilities The table below shows examples of what Cleric can access from commonly used integrations. [Supported Integrations](/integrations/supported-integrations) is the complete list, with setup steps and the permissions each one needs. Every integration listed there is generally available on all plans. | Integration | Data Type | Example Tasks | Common Use Cases | | ------------------------------ | -------------- | -------------------------------------------------------------------------- | --------------------------------------------------------------- | | **Amazon Web Services** | Logs | Query CloudWatch logs | Debugging applications, analyzing Lambda executions | | | Metrics | Query CloudWatch metrics | Resource utilization, performance monitoring | | | Resources | Describe EC2 instances, ELBs, Route 53 DNS, ACM certificates | Infrastructure state, DNS configuration, certificate management | | **ClickHouse** | Queries | Read query history, running queries and server errors | Failing or slow queries, when a problem started | | | Storage | Read parts, merges, mutations, replicas, disks and memory | Too many parts, stuck mutations, replica lag | | **Confluence** | Documentation | Retrieve pages from a space, get content of a page | Runbooks, architecture documentation | | **Jira** | Issues | Search issues, get issue details with comments and attachments | Incident history, ticket context | | | Actions | Create issues (requires "Create Issues" permission) | Filing tickets from investigation findings | | **Datadog** | Metrics | Query metrics, list metrics, get metric details | Detecting anomalies, performance degradation | | | Logs | Search and analyze logs, get service tags from logs | Identifying application errors | | | Monitors | Get monitor details | Understanding alert context | | | Dashboards | List dashboards by URL or title | Leveraging existing team context | | | SLOs | Get SLO details | Tracking service reliability | | **Elastic Kubernetes Service** | Events | List events | Detecting deployment issues | | | Logs | Search logs for pods | Identifying application errors, startup issues | | | Resources | List, get, and describe resources (pods, deployments, etc.) | Detecting deployment issues, pod crashes, scaling problems | | | Metrics | Get CPU/memory usage for pods and nodes | Resource contentions, quota exceedances | | **Elasticsearch** | Search Indices | List indices, get field mappings | Understanding data structure | | | Logs | Search with query DSL | Searching application logs, analyzing indexed data | | **GitHub** | Repositories | Get code diff, get commit history, search code, create branches | System context, change history, proposed fixes | | | Issues & PRs | Create issues, open pull requests | Tracking problems, proposing code changes | | | Logs | Analyze workflow logs | Identifying deployment errors | | **Google Cloud Platform** | Logs | Search and filter logs, retrieve log labels | Debugging applications, monitoring cloud infrastructure | | | Metrics | Query Cloud Monitoring metrics | Resource utilization, performance monitoring | | | Resources | Describe Compute instances, Load Balancers, Cloud DNS, Certificate Manager | Infrastructure state, DNS configuration, certificate management | | **Grafana** | Metrics | Query metrics | Detecting anomalies, performance degradation | | | Logs | Search Loki logs | Identifying application errors | | | Alert Rules | List alert rules, get alert rule details by UID | Understanding alert context | | | Dashboards | Get dashboard by UID | Leveraging existing team context | | **Kubernetes** | Events | List events | Detecting deployment issues | | | Logs | Search logs for pods | Identifying application errors, startup issues | | | Resources | List, get, and describe resources (pods, deployments, etc.) | Detecting deployment issues, pod crashes, scaling problems | | | Metrics | Get CPU/memory usage for pods and nodes | Resource contentions, quota exceedances | | **PagerDuty** | Incidents | Get incident details | Alert patterns, on-call load analysis | | | Services | Get service details | Understanding service health | | **Prometheus** | Metrics | Query metrics, list metrics, get metric details | Performance monitoring, resource usage | | | Alert Rules | Get active alert rules, get alert rule details | Understanding alert context | | **Generic MCP** | Custom | Tools defined by the connected MCP server | Extending Cleric with custom data sources | ## MCP Support Cleric integrates with the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) in two directions: * **Generic MCP (Cleric as MCP client):** Cleric connects to an MCP server you run and calls its tools during investigations. See the [Generic MCP](/integrations/supported-integrations#generic-mcp) section of Supported Integrations. * **Cleric MCP Server (Cleric as MCP server):** Cleric exposes an MCP endpoint at `/mcp` that AI coding tools such as Claude Code and Cursor connect to for reading investigation data and creating new investigations. Authenticates with a per-user API key generated from the Settings page. See [MCP Server](/integrations/mcp) for setup. ## Monitoring Integration Health Cleric runs a read-only health check against each configured integration every hour. It tests the connection to the integration's API using the stored credentials. Each integration on the Integrations page displays a status badge: * **Connected**: The last health check succeeded within the past 2 hours * **Error**: No successful health check in the past 2 hours, or the most recent connection test failed When any enabled integration is in the "Error" state, a red indicator appears on the **Integrations** tab in the sidebar. Open the Integrations page to identify which integration is failing. ### Common Causes of Health Check Failures * Expired or rotated API tokens/credentials * Network connectivity changes (firewall rules, IP allowlists) * The external service is temporarily unavailable * Credential permissions were revoked To fix a failing integration, update the credentials and click **Update configuration** to save. ## Enabling and Disabling Integrations Each integration has an **Enable configuration** toggle at the bottom of its configuration form. Disabled integrations are not used during investigations and are not health-checked. They display a **Disabled** badge. # Supported Integrations Configuration instructions for each integration You can add integrations yourself in the web app, or [configure Cleric MCP](/integrations/mcp) and have your coding agent add them for you. Your agent needs access to the systems you want to connect and permission to configure them. To configure connections in the web app: 1. Log in to the Cleric web app (`.app.cleric.ai`) 2. Click on the "Integrations" tab 3. For each integration (Kubernetes, Datadog, Splunk, MongoDB Atlas, PagerDuty, etc): * Click on the integration name * Click "Add connection" or "Connect {integration}" * Fill in the required fields * Click "Save connection" Repeat this process for each integration you want to set up. ## Slack Slack is the primary way to interact with Cleric. Connect your Slack workspace to start investigations automatically and interact with Cleric from Slack. {% hint style="info" %} The Cleric app is not listed in the Slack Marketplace. You install it from the Cleric web app, and Slack may show a notice that the app is not approved by Slack. {% endhint %} ### Steps to Configure {% stepper %} {% step %} #### Connect your Slack workspace In the Cleric Web app, go to **Integrations** and click "Add to Slack" in the Slack section to connect your workspace. {% endstep %} {% step %} #### Invite Cleric to channels In Slack, add Cleric to channels where you want to run investigations using `/invite @Cleric #channel`. {% endstep %} {% step %} #### Start investigating You can start investigations in two ways: * **On-demand**: Mention `@Cleric` in any channel or thread where Cleric is present * **Automatically**: Configure triggers to start investigations on matching alerts or on a schedule (see [Configuring Automations](/setup/agents-and-triggers)) {% endstep %} {% endstepper %} ### What This Enables Once Slack is connected, you can interact with Cleric directly in your channels: {% code overflow="wrap" %} ``` @Cleric Check the health of the checkout service @Cleric Why is pod checkout-abc123 crashing? @Cleric Show me error logs for the last hour @Cleric What changed in the last deployment? ``` {% endcode %} Cleric responds in threads, keeping conversations organized. You can attach files (logs, screenshots, config files) to provide additional context. ## Microsoft Teams Connect Microsoft Teams to investigate alerts, ask questions and verify production changes in your channels. ### Before You Start Use your work or school Microsoft account. You'll need your organisation's Teams administrator to approve Cleric and a team owner to install it. ### Install Cleric {% stepper %} {% step %} #### Connect Your Microsoft Account In Cleric, open **Integrations → Microsoft Teams → Add connection**. Select **Sign in with Microsoft** and sign in to the organisation where you want to use Cleric. {% endstep %} {% step %} #### Get Your Organisation's Approval If **Add to Teams** is already available, continue to the next step. Select **Submit for IT approval** and complete Microsoft sign-in. Ask your organisation's Teams administrator to review Cleric in the [Teams admin center](https://admin.teams.microsoft.com/policies/manage-apps), approve its requested permissions and allow it for your users. Return to Cleric and select **Check approval**. Complete Microsoft sign-in to refresh the result. {% endstep %} {% step %} #### Add Cleric To Your Team Select **Add to Teams**. A team owner chooses the team and approves the requested access. Private and shared channels require their own app installation. {% endstep %} {% step %} #### Send Your First Message In a Teams channel where Cleric is installed, send: ``` @Cleric what can you do? ``` Cleric replies in the thread. In Cleric, select **Refresh channels** to see the channels available to you. {% endstep %} {% endstepper %} ### Start Using Cleric Mention Cleric to investigate a problem: ``` @Cleric investigate the checkout error rate ``` Reply in the same thread to ask follow-up questions. To check a deployment, send `@Cleric !verify` with a pull request link. See [Change Verification](/usage/change-verification). To investigate alerts automatically, select **Manage triggers** and create a **Bot message** trigger for your Teams channel. See [Configuring Automations](/setup/agents-and-triggers). ### Troubleshooting * **IT approval is pending or rejected:** Ask your organisation's Teams administrator to review Cleric in the Teams admin center. After approval, select **Check approval** in Cleric. * **Your channel is missing or Cleric doesn't reply:** Confirm Cleric is installed in that team or channel, mention it there, then select **Refresh channels**. Only channels you can access are listed. To add Cleric to another team later, open your existing Microsoft Teams connection and expand **Add teams or review setup**. ## Amazon Web Services ### How it Works The AWS integration uses [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html) to generate temporary credentials for a role you provision. Cleric never stores long-term AWS credentials. When investigating, Cleric assumes the role, receives temporary credentials, and accesses only what the role's policies allow. ### Required Information * IAM Role ARN * Default AWS Region * Description (to identify the account) ### Steps to Configure {% stepper %} {% step %} #### Get the trust policy from Cleric * In the Cleric Web UI, navigate to "Integrations" > "Amazon Web Services" * Copy the trust policy template displayed on the configuration page * This trust policy allows Cleric to assume the role you'll create {% endstep %} {% step %} #### Create the IAM role in your AWS account * Sign in to the AWS Console and navigate to IAM > Roles * Click "Create role" * Select "Custom trust policy" and paste the trust policy from step 1 * Click "Next" {% endstep %} {% step %} #### Attach the validation policy Create and attach a policy that allows Cleric to validate that the role does not grant write permissions. Use the following policy template, replacing `$your_account_id` and `$your_cleric_roles_name` with your values: {% code overflow="wrap" expandable="true" %} ```json { "Statement": [ { "Action": [ "iam:GetRole", "iam:ListAttachedRolePolicies", "iam:ListRolePolicies", "iam:GetRolePolicy" ], "Effect": "Allow", "Resource": "arn:aws:iam::$your_account_id:role/$your_cleric_roles_name", "Sid": "ReadOwnRoleAndInlinePolicies" }, { "Action": ["iam:GetPolicy", "iam:GetPolicyVersion"], "Effect": "Allow", "Resource": [ "arn:aws:iam::aws:policy/*", "arn:aws:iam::$your_account_id:policy/*" ], "Sid": "ReadPoliciesAttachedToSelf" } ], "Version": "2012-10-17" } ``` {% endcode %} * In the AWS Console, navigate to IAM > Policies > Create policy > JSON * Paste the policy above (with your values substituted) * Name the policy (e.g., "ClericValidationPolicy") and create it * Return to your role creation and attach this policy {% endstep %} {% step %} #### Attach read-only permissions Attach AWS managed policies to grant Cleric read access to the resources you want it to investigate. We recommend starting with: * `arn:aws:iam::aws:policy/CloudWatchReadOnlyAccess` * `arn:aws:iam::aws:policy/CloudWatchLogsReadOnlyAccess` * `arn:aws:iam::aws:policy/ElasticLoadBalancingReadOnly` * `arn:aws:iam::aws:policy/AmazonEC2ReadOnlyAccess` * `arn:aws:iam::aws:policy/AWSCloudTrail_ReadOnlyAccess` `AWSCloudTrail_ReadOnlyAccess` lets Cleric read your CloudTrail event history (`cloudtrail:LookupEvents`) to find AWS API calls that failed or changed configuration around an alert, such as a denied call, a deleted branch or an edited security group. To grant only that, attach a policy allowing `cloudtrail:LookupEvents` on `"Resource": "*"` instead. Cleric reads the event history CloudTrail keeps for every account (management events, last 90 days); it does not need a trail or access to its S3 bucket. If you have ECS or EKS clusters to connect, create customer-managed policies via IAM > Policies > Create policy > JSON, then attach to the role like the validation policy in step 3. **For ECS clusters:** Add a policy with the following permissions and attach it to the role: {% code overflow="wrap" expandable="true" %} ```json { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": ["ecs:Describe*", "ecs:List*"], "Resource": "*" } ] } ``` {% endcode %} **For EKS clusters:** If you plan to connect EKS clusters using the [Elastic Kubernetes Service](#elastic-kubernetes-service) integration, add a policy with the following permissions and attach it to the role: {% code overflow="wrap" expandable="true" %} ```json { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": ["eks:Describe*", "eks:List*"], "Resource": "*" } ] } ``` {% endcode %} > **Note:** You can restrict the `Resource` block to specific cluster ARNs if you want to limit which clusters Cleric can access (e.g., `"arn:aws:eks:us-east-1:123456789012:cluster/my-cluster"`). You can start with whatever permissions you're comfortable with and add more later. Cleric will automatically pick up new permissions without requiring reconfiguration. {% endstep %} {% step %} #### Complete role creation * Add a name for the role (e.g., "ClericRole") * Optionally add a description * Click "Create role" * Copy the role ARN from the role summary page {% endstep %} {% step %} #### Configure the integration in Cleric * In the Cleric Web app, navigate to "Integrations" > "AWS" * Click "Add connection" * Enter the following information: * IAM Role ARN (from step 5) * Description (to identify this AWS account) * Default Region (e.g., "us-east-1") * Click "Save connection" to add the integration (this step will verify that you have only granted read-only permissions) {% endstep %} {% endstepper %} ### Multiple AWS Accounts If you want to give Cleric access to multiple AWS accounts, repeat the configuration process for each account. Create a separate role in each account with the same trust policy, then add a separate integration connection for each account. ### What This Enables With AWS connected, Cleric can investigate infrastructure and application issues: {% code overflow="wrap" %} ``` Query CloudWatch logs for checkout-service errors in the last 2 hours Show me Lambda execution failures since midnight What's the CPU utilization trend for our EC2 instances today? Check if there are any unhealthy targets in the production load balancer Search CloudWatch logs for "timeout" errors across all services ``` {% endcode %} Cleric automatically correlates AWS infrastructure state with application behavior, helping identify issues like resource exhaustion, configuration problems, or service disruptions. ## Amplitude Connect Amplitude to let Cleric correlate product-analytics signals (event volumes, active/new user counts, segmentation, and saved charts) with an incident. For example, Cleric can check whether a key product event dropped when an alert fired, or whether active users fell off around a deploy. ### Prerequisites * An Amplitude project * The project's **API Key** and **Secret Key** (project-scoped, not personal user tokens). Because these keys belong to the project rather than an individual, they keep working when team members leave. > **Read-only note.** Amplitude's API Key / Secret Key pair grants full project access and Amplitude provides no way to scope it to read-only or to introspect its permissions. Cleric only ever issues read-only Dashboard REST and Export API requests (event lists, segmentation, user counts, saved charts, annotations) and never calls ingestion, taxonomy-write, or user-deletion endpoints. Because of this, Cleric cannot verify read-only access at setup time the way it does for integrations that expose token scopes. Treat the Secret Key as sensitive and store it only in Cleric. ### Required Information * **API Key**: from **Settings** > **Projects** > *your project* > **General** * **Secret Key**: shown alongside the API Key on the same page * **Base URL**: select **US** (`https://amplitude.com`, default) or **EU** (`https://analytics.eu.amplitude.com`), matching your project's data residency ### Steps to Configure {% stepper %} {% step %} #### Find your project's API Key and Secret Key * In Amplitude, open **Settings** > **Projects** and select the project Cleric should access * On the **General** tab, copy the **API Key** and the **Secret Key** {% endstep %} {% step %} #### Determine your base URL * If your project uses Amplitude's EU data center, select **EU** for **Base URL** in Cleric; otherwise use **US** {% endstep %} {% step %} #### Configure the integration in Cleric * In the Cleric Web app, navigate to **Integrations** > **Amplitude** * Click **Add connection** * Select the **Base URL**, then enter the **API Key** and **Secret Key** * Click **Save connection** to verify access {% endstep %} {% endstepper %} ### What This Enables With Amplitude connected, Cleric can investigate whether product behavior changed around an incident using the Dashboard REST API. {% code overflow="wrap" %} ``` Did the "Send Email" event volume drop when this alert fired? Were active users lower than usual during the outage window? Is there an Amplitude annotation (deploy/launch) near the time this started? ``` {% endcode %} Cleric reads Amplitude through the Dashboard REST API only (event lists, event segmentation, active/new user counts, saved charts, and annotations). It cannot send events, modify taxonomy, or delete user data. ## Atlassian ### Required Information * Atlassian base URL * Atlassian username or email * Atlassian API token * Optional list of Confluence space keys * Optional list of Jira project keys ### Steps to Obtain Credentials Atlassian API tokens inherit the permissions of the user who creates them. We recommend using a dedicated Atlassian user with read-only access to only the Confluence spaces and Jira projects you want Cleric to access. {% stepper %} {% step %} #### Decide which Confluence spaces and/or Jira projects you want Cleric to access * Identify the Confluence space keys for those spaces * Identify the Jira project keys for those projects {% endstep %} {% step %} #### Create a dedicated Atlassian user with limited access * Create a new Atlassian user (e.g., "cleric-readonly") * Grant it read-only access to only the selected spaces by following [this doc](https://support.atlassian.com/confluence/kb/how-to-grant-access-to-one-space-only-to-a-user-in-confluence/) * Grant it browse/read access to selected Jira projects. The default Viewer role in the Jira Space (f.k.a. Project) Settings should suffice. * If you want Cleric to be able to open Jira tickets, you'll need to grant the user (or the group it belongs to) the "Create Issues" permission on the relevant Jira project * The easiest way to do this is to create a custom role in the Jira Space settings that includes both "Collaborate" and "Create" permissions {% endstep %} {% step %} #### Create an API token for that user and configure Cleric * Go to Atlassian account settings > "Security" > "Create and manage API tokens" * Create a new API token for the new user and copy it * Use the following in the integration: * Atlassian base URL (e.g., "") * The new user's username or email * The new user's API token * Provide at least one of: * The list of Confluence space keys you selected * The list of Jira project keys you selected {% endstep %} {% endstepper %} ### What This Enables With Atlassian connected, Cleric can reference your team's documentation and issue history during investigations: {% code overflow="wrap" %} ``` What does our deployment runbook say about rollback procedures? Search Confluence for the incident response process Check our architecture docs for how the checkout service connects to the payment gateway What are our on-call escalation procedures according to the wiki? Show me recent incidents in Jira project SRE related to checkout timeouts Find Jira issues linked to deployment failures in the PAY project ``` {% endcode %} Cleric uses Confluence documentation and Jira issue context to understand your team's processes, architecture decisions, and historical incident patterns, making investigations more context-aware. ## Better Stack Cleric can read logs, traces and metrics from [Better Stack](https://betterstack.com) when it investigates an alert, and see which uptime monitors are down and which incidents are open. ### Prerequisites * A Better Stack Telemetry source that receives your logs, traces or metrics. * The **Admin** role in Better Stack, to create an API token. ### Required Information * **Query Host**, **Username** and **Password**: the read-only credentials Better Stack gives you for querying your data. They reach every source of the teams you pick. * **API Token**: a Global API token with **Read only** permission. Please don't give Cleric a token that can write. It will reject it for safety. **Note:** Cleric never creates, changes or acknowledges monitors, incidents or sources. Its queries count toward your Better Stack query limits. ### Steps to Configure {% stepper %} {% step %} #### Create query credentials In Better Stack, open **Integrations** and click **Connect** on **ClickHouse HTTP client**. Pick the teams whose sources Cleric should read and click **Create connection**. Copy the password now: Better Stack won't show it again. Note the host and username too. {% endstep %} {% step %} #### Create a read-only API token Signed in as an Admin, open **API tokens**, create a **Global API token** named `Cleric` with **Read only** permission, and copy it. {% endstep %} {% step %} #### Configure the integration in Cleric In Cleric, open **Integrations** > **Better Stack**, click **Add connection**, enter the host, username, password and token, and click **Save connection**. Cleric checks them before it saves. {% endstep %} {% endstepper %} ### What This Enables Ask Cleric things like: * Which errors did checkout log in the last 30 minutes? * Show me the slowest traces for POST /orders since 14:00. * Is the API monitor down, and when did the incident start? ## Bitbucket Cloud Connect Bitbucket Cloud to let Cleric inspect source code, commits, pull requests, and Bitbucket Pipelines during investigations. Cleric can also create a branch, push a requested change, and open a pull request for review. ### Prerequisites * Administrator access to the Bitbucket workspace you want to connect * A repository URL from that workspace, which you can use to find the workspace slug {% hint style="info" %} This integration supports Bitbucket Cloud. It does not support Bitbucket Data Center or Bitbucket Server. {% endhint %} ### Steps to Configure {% stepper %} {% step %} #### Create an OAuth client In Bitbucket Cloud: 1. Open the workspace you want Cleric to access. 2. Select the settings cog, then **Workspace settings**. 3. Under **Apps and features**, select **OAuth clients**. 4. Select **Create OAuth client**. 5. Enter `Cleric` as the name and complete any other required fields. If Bitbucket requires a callback URL, enter `https://www.cleric.ai`. Cleric does not redirect to this URL when using Client credentials. {% endstep %} {% step %} #### Configure permissions Under **Authorization**, select **Client credentials**. Under **Scopes**, select: | Permission | Access | | ------------- | ------ | | Repositories | Write | | Pull requests | Write | | Pipelines | Read | Leave the remaining permissions unset. Select **Save**, then copy the generated **Client ID** and **Client secret**. {% endstep %} {% step %} #### Add the configuration in Cleric In Cleric, go to **Integrations > Bitbucket** and select **Add connection**. Enter: * **Workspace slug:** The first path segment after `bitbucket.org` in a repository URL. For example, if the repository URL is `https://bitbucket.org/acme/checkout-service`, enter `acme`. * **Client ID:** The Client ID from the Bitbucket OAuth client. * **Client secret:** The Client secret from the same OAuth client. Select **Test connection**. When the test succeeds, select **Save connection**. {% endstep %} {% endstepper %} {% hint style="warning" %} Treat the Client secret like a password. Enter it only in Cleric. {% endhint %} ### What This Enables With Bitbucket connected, Cleric can investigate code and CI/CD activity: {% code overflow="wrap" %} ``` What changed in the last deployment of checkout-service? Show me the code diff for the most recent commit to main Why did the last three Bitbucket Pipelines runs fail? Was this regression introduced by a recent pull request? Fix the timeout handling and open a pull request for review ``` {% endcode %} Cleric only pushes changes to a new branch and opens a pull request when you request a code change. It does not merge pull requests or push directly to the default branch. ### Multiple Workspaces Create a separate OAuth client and Cleric configuration for each Bitbucket workspace. ### Troubleshooting * **Bitbucket rejects the credentials:** Verify the Client ID and Client secret, and confirm that **Client credentials** is enabled on the OAuth client. * **The connection shows an error:** Verify the workspace slug and the three required permissions, then test the configuration again. * **A repository is missing:** Confirm that you created the OAuth client in the workspace that owns the repository. For more information, see [Use OAuth on Bitbucket Cloud](https://support.atlassian.com/bitbucket-cloud/docs/use-oauth-on-bitbucket-cloud/) and [Bitbucket Cloud REST API scopes](https://developer.atlassian.com/cloud/bitbucket/bitbucket-cloud-rest-api-scopes/). ## BuildKite Connect BuildKite to let Cleric inspect CI/CD pipelines, builds, jobs, build logs, and annotations to diagnose failing deploys and pipelines. ### Prerequisites * A BuildKite organization * A BuildKite user account for Cleric to authenticate as. BuildKite API access tokens are owned by the user who creates them, so we recommend using a shared service-account user rather than an individual's account. Personal tokens stop working when that user is removed from the organization. * A **REST API access token** created from that account, restricted to your organization and to read scopes only. Cleric validates the token scopes during setup and rejects tokens that include any write or delete scope. ### Required Information * BuildKite **organization slug** (from your dashboard URL `https://buildkite.com/`) * A BuildKite **API Access Token** with these scopes (exact dashboard names): * **Read Builds** * **Read Build Logs** * **Read Pipelines** * **Read Organizations** ### Steps to Configure {% stepper %} {% step %} #### Create a read-only API access token * Sign in as a shared service account and open [**API Access Tokens**](https://buildkite.com/user/api-access-tokens) (User Settings > API Access Tokens) * Click **New API Access Token** * Under **Organization Access**, restrict the token to the organization Cleric should see * Under **REST API Scopes**, enable **only**: Read Builds, Read Build Logs, Read Pipelines, Read Organizations * Leave GraphQL API access disabled and do not enable any write scopes * Create the token and copy its value {% endstep %} {% step %} #### Find your organization slug * Open your BuildKite dashboard and copy the slug from the URL `https://buildkite.com/` {% endstep %} {% step %} #### Configure the integration in Cleric * In the Cleric Web app, navigate to **Integrations** > **BuildKite** * Click **Add connection** * Enter the organization slug and API access token * Click **Save connection** to verify access {% endstep %} {% endstepper %} ### What This Enables With BuildKite connected, Cleric can investigate CI/CD failures by finding failing builds across pipelines, branches, or commits, drilling into job logs, and reading build annotations. {% code overflow="wrap" %} ``` Why did the latest deploy pipeline build fail on main? Show the failing job's log for build #1234 of the api pipeline Did this CI failure start after a specific commit? ``` {% endcode %} Cleric reads BuildKite through the REST API only. It cannot create, retry, cancel, or modify builds, and it does not access Secrets, Packages and Registries, or Test Engine data. ## ClickHouse Connect a ClickHouse server or ClickHouse Cloud service so Cleric can see what it is doing during an investigation: failing and slow queries, failing inserts, too many parts, stuck merges and mutations, replication, memory and disk. When you grant it, Cleric can also query data you store in ClickHouse, such as logs and events. Cleric's access is read-only. ### How it Works Cleric queries ClickHouse over its HTTP interface with a user you create for it. Every query Cleric sends: * runs with `readonly = 1`, so the server refuses writes, DDL and `SET`, and a query cannot raise Cleric's limits; * stops after 30 seconds and returns at most 1,000 rows; * runs as a single statement, with values passed as typed query parameters. Cleric also refuses queries with a `SETTINGS` clause, and table functions that read from outside the server (`url`, `s3`, `file`, `remote` and similar). The password is used only by Cleric's own service. It is never passed to the agent's sandbox. ClickHouse keeps a history of every query in `system.query_log`, so Cleric can look at the time of the incident itself, not only at the server's state when it looks. ### Required Information * **Host**: the HTTP interface URL with its port, for example `https://abc123.us-east-1.aws.clickhouse.cloud:8443` or `http://clickhouse.internal:8123` * **Database**: the default database for queries (usually `default`) * **CA Certificate**: only if the server's certificate is not signed by a public CA (see [Encryption](#encryption)) * **Username** and **Password** of a user created for Cleric ### Permissions Create a dedicated user that can only read the system tables, plus any databases whose data you want Cleric to query: {% code overflow="wrap" %} ```sql CREATE USER cleric IDENTIFIED WITH sha256_password BY ''; GRANT SELECT ON system.* TO cleric; -- Optional: on a cluster (including every ClickHouse Cloud service), read all replicas' query logs GRANT READ ON REMOTE TO cleric; -- Optional: data Cleric may query, for example logs and events GRANT SELECT ON logs.* TO cleric; ``` {% endcode %} Don't give the user a `readonly` settings profile. Cleric makes every query read-only itself. A profile pinned to `readonly = 1` also stops Cleric from applying its time and row limits and returning UTC timestamps. If your policy requires a profile, use `readonly = 2`. When you save the connection, Cleric reads the user's grants, including grants through roles, and rejects the user if it holds anything beyond `SELECT` (and `READ ON REMOTE`). That includes `INSERT`, `ALTER`, `CREATE`, `DROP`, `TRUNCATE`, `SYSTEM`, `KILL QUERY`, access management, and reading from URLs, files or S3. ClickHouse Cloud's `default` user fails this check. Use a dedicated user. ### Network Access * **ClickHouse Cloud or a public endpoint**: add Cleric's [static egress IP](/security/security-data-privacy#network-security-egress) to the service's IP access list or your firewall. * **Private server**: use the [Cleric Connector](/integrations/private-resources). Add the server's host and HTTP port to the Connector's endpoints, then enter the same URL in Cleric. ### Encryption Use `https://` with the HTTPS port (8443 by default). Cleric verifies the server's certificate against public CAs, or against the CA certificate you paste, base64-encoded: {% code overflow="wrap" %} ```bash base64 < ca.pem | tr -d '\n' ``` {% endcode %} Use `http://` only for a server reachable only on a private network or through the Cleric Connector. ### Supported and Unsupported Data Cleric reads: * **Query history**: `system.query_log`, including failures by error code, slow statements, users and tables * **Running queries**: `system.processes` * **Server errors**: `system.errors` * **Storage**: `system.parts`, `system.merges`, `system.mutations`, `system.disks`, and table sizes and settings * **Replication**: `system.replicas`, `system.replication_queue`, `system.distribution_queue`, and the Keeper connection * **Resource history**: `system.metric_log`, `system.asynchronous_metric_log` and `system.part_log`, where enabled * **Your data**: tables in databases you granted `SELECT` on Cleric never: * writes data, changes settings, or runs DDL * kills queries or runs `SYSTEM` commands * reads from URLs, S3, files or other servers, except its own cluster's replicas with `READ ON REMOTE` ### Steps to Configure {% stepper %} {% step %} #### Create the user Connect as an administrator and run the statements under [Permissions](#permissions). {% endstep %} {% step %} #### Allow Cleric to connect Add Cleric's egress IP to the IP access list, or add the server to the Cleric Connector, as described under [Network Access](#network-access). {% endstep %} {% step %} #### Add to Cleric In the Cleric Web app, go to **Integrations** > **ClickHouse** > **Add connection**. Enter the host URL, database, CA certificate if needed, username and password, then click **Save connection**. Cleric connects and checks the user's grants before saving. {% endstep %} {% endstepper %} ### What This Enables {% code overflow="wrap" %} ``` Why are inserts into the events table failing? Which queries failed on ClickHouse in the last hour, and when did it start? Is ClickHouse running out of memory or disk? Are any replicas lagging or read-only? How many checkout errors were logged in the last 30 minutes? ``` {% endcode %} ## Cloudflare Connect Cloudflare to let Cleric query DNS records, WAF/security events, Workers, traffic analytics, load balancer health, SSL/TLS status, and audit logs using the Cloudflare API v4 and GraphQL Analytics API. ### Prerequisites * A Cloudflare account * A **read-only API Token** with the appropriate permission groups * Your **Account ID** ### Steps to Configure {% stepper %} {% step %} #### Create an Account-Level Read-Only API Token {% hint style="warning" %} **Use account-level API Tokens only.** Do not use personal tokens created under **My Profile**. Those are tied to an individual user and will stop working if that person leaves the organization. Account-level tokens authenticate as the organization, not as a person. {% endhint %} * Log in to the Cloudflare dashboard and navigate to **Manage Account** > **Account API Tokens** * Click **Create Token** * Use the **Custom token** template * Add these **read-only** permissions (names match the Cloudflare dashboard exactly): | Category | Permission | Level | | ------------------- | ---------------------------------- | ----- | | Account & Billing | Account API Tokens | Read | | DNS & Zones | DNS View | Read | | App Security | Account WAF | Read | | App Security | Account Firewall Access Rules | Read | | Analytics & Logs | Account Analytics | Read | | Analytics & Logs | Account Logs | Read | | Developer Platform | Workers Scripts | Read | | Developer Platform | Workers Observability | Read | | Network Services | Account Load Balancers | Read | | Network Services | Load Balancing: Monitors and Pools | Read | | Cache & Performance | Account SSL & Certificates | Read |

The Account API Tokens: Read scope is required so Cleric can verify that the token has only read-only permissions. Without it, Cleric cannot validate the token's scopes and will reject the connection.

* Under **Account Resources**, select your account * Under **Zone Resources**, select "All zones" or specific zones * Optionally set an IP filter and expiration date for additional security * Click **Continue to summary** then **Create Token** * Copy the token immediately. It is only shown once. {% endstep %} {% step %} #### Find your Account ID * In the Cloudflare dashboard, your Account ID appears on the right sidebar of any zone's **Overview** page, or under **Account Home** {% endstep %} {% step %} #### Configure the integration in Cleric * In the Cleric Web app, navigate to **Integrations** > **Cloudflare** * Click **Add connection** * Enter your Account ID and API Token * Click **Save connection** to verify access {% endstep %} {% endstepper %} ### What This Enables With Cloudflare connected, Cleric can investigate DNS issues, WAF events, Worker errors, traffic anomalies, and more: {% code overflow="wrap" %} ``` Are there any WAF events blocking traffic to the checkout page? Show me the DNS records for example.com What is the error rate for Workers in the last hour? Were there any configuration changes in Cloudflare around the time of the incident? ``` {% endcode %} ### Supported and Unsupported APIs Cleric currently supports the following Cloudflare data surfaces for **read-only** investigation: | API Surface | Status | What Cleric Can Do | | --------------------- | --------- | --------------------------------------------------------------------------------- | | DNS records | Supported | List and query DNS records across zones | | WAF / Security events | Supported | Query firewall events (blocked, challenged, logged requests) via GraphQL | | Traffic analytics | Supported | HTTP request analytics (status codes, cache rates, bandwidth) via GraphQL | | Workers | Supported | List scripts, query invocation analytics (errors, CPU time, duration) via GraphQL | | Load balancers | Supported | Pool health, origin status, failover configuration | | SSL/TLS | Supported | Certificate packs, verification status, SSL mode | | Audit logs | Supported | Account audit trail (who changed what, when) | | Zone management | Supported | List zones, status, plan, name servers | The following Cloudflare categories are **not currently supported**: | Category | Reason | | --------------------------------------------------------------- | ------------------------------------ | | Developer Platform (D1, R2, KV, Pages, Queues, Pipelines, etc.) | Not yet needed for SRE investigation | | AI & Machine Learning (AI Gateway, Workers AI, Agents) | Not yet needed for SRE investigation | | Cloudflare One / Zero Trust (Access, CASB, Tunnels, WARP) | Not yet needed for SRE investigation | | Rules & Configuration (Rulesets, Transform Rules, Redirects) | Not yet needed for SRE investigation | | Network Services (Magic Transit, Magic WAN, IP Prefixes) | Not yet needed for SRE investigation | | Media (Stream, Images) | Not yet needed for SRE investigation | | Email & Messaging (Email Routing, Email Security) | Not yet needed for SRE investigation | | Account & Billing (Billing, Notifications, API Gateway) | Not yet needed for SRE investigation | These can be added in future releases as customer needs arise. Each requires adding the corresponding read-only scope to the API token and a new skill script. ## Datadog ### Required Information * **Host** (select your Datadog site from the dropdown) * Datadog API Key * Datadog Application Key ### Steps to Configure {% stepper %} {% step %} #### Get your API key Go to **Organization Settings** > **API Keys**. Copy an existing key or create a new one. {% endstep %} {% step %} #### Determine your Datadog site When adding the connection in Cleric, select your Datadog site in the **Host** dropdown. The available options are: | Site | API endpoint | | ------- | ------------------------------- | | US1 | `https://api.datadoghq.com` | | US3 | `https://api.us3.datadoghq.com` | | US5 | `https://api.us5.datadoghq.com` | | EU1 | `https://api.datadoghq.eu` | | AP1 | `https://api.ap1.datadoghq.com` | | US1-FED | `https://api.ddog-gov.com` | To find your site, check the URL when logged into Datadog. The subdomain indicates your region (e.g., `us5.datadoghq.com` → US5). {% endstep %} {% step %} #### Create a read-only role 1. Go to **Organization Settings** > **Roles** > **+ New Role** 2. Name it `Cleric Integration` 3. Enable **read** permissions for the following categories: * APM & Traces * Continuous Profiler * Logs * Dashboards * Notebooks * Monitors * SLOs * Incidents & Cases * Error Tracking * Events * RUM & Session Replay * Synthetics * Database Monitoring * CI/CD Visibility * Cloud Cost Management * Infrastructure * Security Signals 4. Do not grant any write, edit, or delete permissions 5. Click **Save** {% endstep %} {% step %} #### Create a service account 1. Go to **Organization Settings** > **Service Accounts** > **+ New Service Account** 2. Name it `cleric-integration` and assign the `Cleric Integration` role 3. Click **Create Service Account** 4. In the Application Keys section, click **+ New Key** 5. Leave the key **unscoped** (do not add scopes to the application key; permissions are controlled by the role) 6. Copy the key (you won't see it again) {% endstep %} {% step %} #### Add to Cleric In the Cleric Web app, go to **Integrations** > **Datadog** > **Add connection**. Select your Datadog site in the **Host** dropdown, enter your **API Key** and **Application Key**, then click **Save connection**. {% endstep %} {% endstepper %} {% hint style="info" %} **Optional:** To restrict Cleric to specific logs, go to **Logs** > **Configuration** > **Data Access** and create a restriction query for the Cleric Integration role (e.g., `service:my-app AND env:production`). Cleric will only see logs matching that query. {% endhint %} ### What This Enables With Datadog connected, Cleric can analyze logs, metrics, monitors, and dashboards: {% code overflow="wrap" %} ``` Show me error logs for checkout-service in the last hour What caused the most recent "High Memory Usage" alert to fire? Compare current API latency to baseline using Datadog metrics Check the system-overview dashboard for anomalies What services have the highest error rate increase since this morning? Show me all active monitors for the production environment ``` {% endcode %} Cleric correlates Datadog data across logs, metrics, and alerts to identify patterns and root causes that might not be obvious from individual data points. ## Elastic Kubernetes Service The Elastic Kubernetes Service (EKS) integration allows Cleric to access Kubernetes clusters running on Amazon EKS. This integration combines AWS IAM authentication with Kubernetes RBAC to provide secure, read-only access to your EKS clusters. ### Prerequisites You must have an existing [AWS integration](#amazon-web-services) configured for the AWS account containing your EKS cluster, with EKS permissions attached to the IAM role. ### Required Information * EKS Cluster ARN * Host (the API server hostname, found in the EKS console under your cluster's details) * Description (to identify this cluster) ### Steps to Configure {% stepper %} {% step %} #### Create the ClusterRole Apply the `cleric-role` ClusterRole to your EKS cluster. See the [Kubernetes integration](#kubernetes) for the full ClusterRole definition. {% endstep %} {% step %} #### Create the ClusterRoleBinding Create a ClusterRoleBinding that assigns the `cleric-role` to the `cleric` group: {% code overflow="wrap" expandable="true" %} ```shell kubectl apply -f - < "Access entries" 3. Click "Create access entry" 4. Select your Cleric IAM role as the principal 5. Add `cleric` to the Kubernetes groups 6. Click "Create" **Option B: aws-auth ConfigMap** Use the aws-auth ConfigMap if your cluster uses the ConfigMap authentication mode. See [aws-auth ConfigMap documentation](https://docs.aws.amazon.com/eks/latest/userguide/auth-configmap.html) for details. Edit the aws-auth ConfigMap: {% code overflow="wrap" %} ```shell kubectl edit configmap aws-auth -n kube-system ``` {% endcode %} Add an entry to the existing `mapRoles` list (do not replace the entire list): {% code overflow="wrap" %} ```yaml - rolearn: arn:aws:iam::ACCOUNT_ID:role/YOUR_CLERIC_ROLE_NAME groups: - cleric ``` {% endcode %} Replace `ACCOUNT_ID` and `YOUR_CLERIC_ROLE_NAME` with your values. {% endstep %} {% step %} #### Configure the integration in the Cleric UI In the Cleric Web app: 1. Navigate to "Integrations" > "Elastic Kubernetes Service" 2. Click "Add connection" 3. Enter the following information: * Cluster ARN (e.g., `arn:aws:eks:us-east-1:123456789012:cluster/my-cluster`) * Host (the API server endpoint from the EKS console, e.g., `https://ABCD1234.gr7.us-east-1.eks.amazonaws.com`) * Description (to identify this cluster) 4. Click "Save connection" {% endstep %} {% endstepper %} ### Multiple EKS Clusters To give Cleric access to multiple EKS clusters: * **Same AWS account:** Create the ClusterRole, ClusterRoleBinding, and access entry/ConfigMap mapping in each cluster, then add a separate EKS integration for each cluster. * **Different AWS accounts:** Ensure you have an AWS integration for each account, then follow the full configuration process for each cluster. ### What This Enables With EKS connected, Cleric can investigate your Amazon EKS clusters using IAM authentication: {% code overflow="wrap" %} ``` List all pods in the production EKS cluster Why is the checkout-service pod OOMKilled in the EKS cluster? Show me node status and resource utilization in the EKS cluster What deployments changed in the last 24 hours in EKS? ``` {% endcode %} EKS integration provides the same Kubernetes investigation capabilities as the standard Kubernetes integration, but uses AWS IAM for authentication instead of long-lived tokens, providing better security and audit trails. ## Elasticsearch ### Required Information * Elasticsearch cluster URL * Elasticsearch API key ### Steps to Obtain Credentials {% stepper %} {% step %} #### Ensure you have permissions to create API keys {% endstep %} {% step %} #### Sign in to your Elasticsearch management interface Sign in to your Elasticsearch management interface (e.g., Kibana) {% endstep %} {% step %} #### Navigate to API keys Navigate to "Management" > "Security" > "API keys" and click "Create API key" {% endstep %} {% step %} #### Create the API key Enter a name for the key, select "Read-only" under "Control security privileges", then click "Create API key" {% endstep %} {% step %} #### Note down the encoded API key Note down the encoded API key for use in the Cleric web app {% endstep %} {% endstepper %} ### What This Enables With Elasticsearch connected, Cleric can search and analyze indexed logs: {% code overflow="wrap" %} ``` Search Elasticsearch for errors related to user 3bc96ec9 Show me all timeout errors in the checkout-service index from the last 4 hours What are the most common error patterns in production logs today? Find logs matching "payment failed" and group by error type ``` {% endcode %} Cleric uses Elasticsearch's powerful search capabilities to quickly find relevant logs and identify patterns across large volumes of indexed data. ## Jaeger Connect Cleric to your Jaeger Query service to search distributed traces and inspect failing or slow spans across services. ### Connection settings * **Query URL**: the Jaeger Query base URL, for example `https://jaeger.example.com` or `http://jaeger-query:16686/jaeger`. Include your deployment's port and path prefix. Do not append `/api`, a trace link, or a collector/OTLP endpoint. * **Bearer Token**: a service token accepted by your authentication proxy, if required. * **Username** and **Password**: service-account credentials for a proxy using basic authentication. Use either a bearer token or basic authentication. Leave all credential fields empty only when the Query endpoint does not require authentication. In **Integrations**, select **Jaeger**, add a connection, enter these settings, and test it. The connection test reads `/api/services`; an empty service list is valid. For a private deployment, configure the Query host and port in your Cleric Connector. Cleric derives firewall destinations from the configured host; Jaeger has no shared SaaS API domain. ### Access and permissions Jaeger authentication and authorization depend on your deployment's proxy. Use an organization-managed service identity rather than a personal account. Restrict it to GET requests on `/api/services`, `/api/operations`, `/api/traces`, and `/api/traces/{id}` under the configured path prefix. Deny collector, archive, administration, and write routes. Jaeger has no standard token-permission introspection endpoint, so Cleric cannot certify the credential's granted permissions during connection testing. Cleric queries Jaeger with the configured endpoint and credentials, subject to its read-only instructions and the service identity's proxy permissions. ### Supported APIs Cleric uses the Jaeger UI's HTTP JSON Query API, available on Jaeger v1 and v2 deployments that expose `/api`. It reads service and operation names, searches by service, operation, tags, time window and span duration, and retrieves individual traces with span references, tags, process metadata and span logs. Search times use microseconds since epoch; duration filters use Go durations such as `500ms` or `2s`. The integration does not use the gRPC or `/api/v3` APIs, span ingestion, trace archiving, sampling configuration, storage administration, or span-metrics APIs. The HTTP JSON API is an internal Jaeger API and can change across releases. See the [Jaeger API documentation](https://www.jaegertracing.io/docs/latest/architecture/apis/). Results depend on your retention, sampling, instrumentation and proxy access. Search results are samples; they do not establish population error rates or latency percentiles. There is no Jaeger subscription requirement; your deployment controls access and retention. ## Render Connect Render so Cleric can read your Render services, deploys, events, logs, and metrics during investigations. ### Prerequisites * A Render workspace with access to [scoped API keys](https://render.com/docs/scoped-api-keys). Scoped API keys are in early access at Render; if you can't create one, request access from Render. * A member role in that workspace that can view the resources Cleric should read. A scoped key can't grant more than its creator's role allows. ### Permissions Create a scoped API key for the workspace Cleric should read. Set each permission to **Read** wherever Render offers it, and to **None** wherever it doesn't. A scoped key reaches one workspace. To connect more than one, create a key and a Cleric connection for each workspace. ### Steps to Configure {% stepper %} {% step %} #### Create a scoped API key * In Render, open **Account Settings** and click **Create API key**. * Name the key and select the workspace Cleric should read. * Set each permission as described above * Click **Generate API key** and copy the key. Render displays it only once. {% endstep %} {% step %} #### Configure the integration in Cleric * In the Cleric Web app, navigate to **Integrations → Render**. * Click **Add connection** and paste the **API Key**. * Click **Save connection**. * Cleric checks that the key can read services, deploys, and monitoring data before accepting the configuration. {% endstep %} {% endstepper %} ## Generic MCP The Generic MCP integration lets you connect any [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server to Cleric. This extends Cleric's capabilities beyond built-in integrations, allowing it to use custom tools and data sources that your team provides through an MCP server. {% hint style="warning" %} **No read-only guarantee.** Unlike built-in integrations, Cleric cannot verify that a Generic MCP server only exposes read-only operations. The tools available to Cleric are entirely defined by the connected MCP server. It is your responsibility to ensure the MCP server only exposes operations appropriate for Cleric to perform. {% endhint %} ### How it Works Cleric connects to your MCP server over HTTP using the [Streamable HTTP transport](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http). Once connected, Cleric discovers the tools the server exposes and makes them available during investigations. Cleric's agent decides when to call these tools based on the investigation context. ### Required Information * MCP server URL * Authorization header (if the server requires authentication) ### Authentication The Generic MCP integration supports **HTTP header-based authentication only**. You provide a single HTTP header in `name: value` format. This header is sent with every request to the MCP server. Common examples: | Auth Method | Header Format | | ------------ | ---------------------------------------- | | Bearer token | `Authorization: Bearer your-token` | | API key | `X-API-Key: your-key` | | Basic auth | `Authorization: Basic base64(user:pass)` | If your MCP server does not require authentication, leave the authorization header field empty. ### Steps to Configure {% stepper %} {% step %} #### Ensure your MCP server is reachable Your MCP server must be accessible from Cleric's network. If the server runs on private infrastructure, configure network access using the [Connecting Private Resources](/integrations/private-resources) guide. {% endstep %} {% step %} #### Add the integration in Cleric In the Cleric Web app, go to **Integrations** > **Generic MCP** > **Add connection**. Enter: * **URL**: The full URL of your MCP server endpoint (e.g., `https://mcp.example.com/mcp`) * **Authorization Header**: The header value in `name: value` format (e.g., `Authorization: Bearer your-token`) {% endstep %} {% step %} #### Save and verify Click **Save connection**. Cleric will test the connection to your MCP server and display a health status. {% endstep %} {% endstepper %} ### Multiple MCP Servers You can connect multiple MCP servers by adding a separate configuration for each. Cleric will discover and use tools from all connected servers during investigations. ### What This Enables With a Generic MCP server connected, Cleric can use whatever tools your server exposes: {% code overflow="wrap" %} ``` Query our internal analytics API for error rates by region Check the deployment status in our custom release management system Look up customer configuration in our internal tools Search our internal knowledge base for known issues related to this error ``` {% endcode %} The specific capabilities depend entirely on the tools your MCP server provides. Cleric treats them like any other integration tool, calling them as needed during investigations. ## GitHub ### How it Works The GitHub integration uses a [GitHub App](https://docs.github.com/en/apps/overview) for authentication. You select which repositories to grant access during installation. The default permission set is: | Permission | Access | What this allows | | ------------- | -------------- | ------------------------------------------------------------------------- | | Actions | Read-only | View and analyze CI/CD workflow logs | | Checks | Read-only | View check run and check suite results | | Contents | Read and write | Search code, view commit history and diffs, create branches, push commits | | Issues | Read and write | View, create, and comment on issues | | Metadata | Read-only | Access repository metadata (names, descriptions, topics) | | Pull requests | Read and write | View pull request status and diffs, and open pull requests | The agent primarily uses the `gh` CLI, authenticated with a short-lived installation token scoped to the App's permissions and the repositories selected during installation. Cleric creates an ephemeral sandbox for each investigation. All working data is stored temporarily and deleted based on your configured retention period. All actions are logged. Cleric is instructed that it cannot merge pull requests or push directly to your default branch. {% hint style="warning" %} **We recommend configuring branch protection rules on your default branch.** If your organization already requires a pull request with at least 1 approval before merging, that sufficiently restricts the agent. If not, the minimum recommended rule is "Restrict who can push to matching branches" on your default branch, with your team(s) on the allowlist and the Cleric app excluded. The default force push and branch deletion restrictions should also be retained on protected branches. {% endhint %} ### Prerequisites Organization owners can install GitHub Apps. Repository admins can install GitHub Apps if they only grant access to repos they admin. Other organization members can request installation, and GitHub sends a notification to the org owner. A GitHub organization owner must approve the permissions when installing or updating the Cleric GitHub App. This is done in your GitHub organization settings under Installed GitHub Apps. ### Installation Steps {% stepper %} {% step %} #### Click 'Connect GitHub' In Cleric web app, go to "Integrations" > "GitHub" and click "Connect GitHub" {% endstep %} {% step %} #### Select the organization Select the organization you want Cleric to access {% endstep %} {% step %} #### Select repositories and authorize Select repositories and authorize the Cleric GitHub app. Review and approve the requested permissions. {% endstep %} {% step %} #### Complete installation After successful installation you will be redirected back to the Integrations page. {% endstep %} {% endstepper %} ### What This Enables With GitHub connected, Cleric can analyze code, deployments, and CI/CD workflows: {% code overflow="wrap" %} ``` What changed in the last deployment of checkout-service? Show me the code diff for the most recent commit to main Why did the last 3 web-app pipeline runs fail? Search the codebase for where we initialize the payment gateway client What was modified in the authentication flow in the last week? Check if there are any failing GitHub Actions workflows ``` {% endcode %} With write permissions, Cleric can also take action during investigations: {% code overflow="wrap" %} ``` Create a GitHub issue summarizing this problem and the potential solutions. Add debug logs to this flow and create a draft PR for me to review. Open an issue with the error details so the team can track this. ``` {% endcode %} Cleric correlates code changes with production issues, helping identify if recent commits, configuration changes, or CI/CD failures are related to observed problems. ## Google Cloud Platform ### Required Information * Project ID * Service account key (base64 encoded) ### Steps to Obtain Credentials {% stepper %} {% step %} #### Ensure you have the required permissions Ensure you have the following IAM roles on your GCP project: * Service Account Creator (`roles/iam.serviceAccountCreator`) - to create service accounts * Project IAM Admin (`roles/resourcemanager.projectIamAdmin`) - to grant roles to the service account {% endstep %} {% step %} #### Create the service account 1. Sign in to the [Google Cloud Console](https://console.cloud.google.com) 2. Navigate to **IAM & Admin** > **Service Accounts** 3. Click **Create Service Account** 4. Enter a service account name (e.g., "cleric-integration") 5. Click **Create and Continue** {% endstep %} {% step %} #### Grant appropriate roles to the service account Grant the service account read-only access to the resources you want Cleric to investigate. We recommend starting with these roles (adjust this list to reflect the services you use): * `roles/monitoring.viewer` - View Cloud Monitoring metrics * `roles/logging.viewer` - View Cloud Logging logs * `roles/container.viewer` - View GKE clusters and workloads (if you run on GKE) * `roles/run.viewer` - View Cloud Run services, revisions and jobs (if you run on Cloud Run) * `roles/cloudsql.viewer` - View Cloud SQL instance configuration (if you use Cloud SQL) * `roles/compute.viewer` - View Compute Engine instances * `roles/dns.reader` - View Cloud DNS records * `roles/certificatemanager.viewer` - View SSL certificates `roles/monitoring.viewer` is the most important of these. Cleric builds its inventory of your running services from Cloud Monitoring, so it works even if you grant nothing else. Pick the runtime role that matches how you deploy: `roles/container.viewer` for GKE, `roles/run.viewer` for Cloud Run. Some of these roles allow reading workload definitions, which include environment variables. If you keep secrets inline in environment variables rather than in Secret Manager, take that into account when deciding which roles to grant. Select each role from the dropdown, then click **Continue**. You can add more roles later as needed. {% endstep %} {% step %} #### Complete service account creation Click **Done** to create the service account {% endstep %} {% step %} #### Create and download the JSON key 1. Click on the email address of the newly created service account 2. Go to the **Keys** tab 3. Click **Add Key** > **Create new key** 4. Select **JSON** as the key type 5. Click **Create** The JSON key file will be automatically downloaded to your machine. Store this file securely as it contains credentials that provide access to your GCP resources. {% endstep %} {% step %} #### Encode the key file Encode the downloaded JSON key file using base64: {% tabs %} {% tab title="macOS" %} {% code overflow="wrap" %} ```bash base64 -i your-service-account-key.json | pbcopy ``` {% endcode %} The encoded key is now in your clipboard. Paste it directly into the Cleric web app. {% endtab %} {% tab title="Linux" %} {% code overflow="wrap" %} ```bash base64 -w 0 your-service-account-key.json ``` {% endcode %} {% endtab %} {% tab title="Platform-agnostic" %} {% code overflow="wrap" %} ```bash cat your-service-account-key.json | base64 | tr -d '\n' ``` {% endcode %} {% endtab %} {% endtabs %} Copy the output string for use in the Cleric web app. {% endstep %} {% step %} #### Note down the required information for use in the Cleric web app * Your project ID * The base64-encoded service account key {% endstep %} {% endstepper %} ### What This Enables With GCP connected, Cleric can investigate infrastructure and application issues: {% code overflow="wrap" %} ``` Query Cloud Logging for errors in the checkout-service in the last 2 hours Show me GKE cluster health and any node issues What's the memory utilization trend for Compute Engine instances today? Check Cloud Monitoring metrics for elevated error rates Search Cloud Logs for "connection timeout" across all services ``` {% endcode %} Cleric automatically correlates GCP infrastructure state with application behavior, helping identify resource exhaustion, configuration issues, or service disruptions. ## Grafana ### Required Information * Grafana server URL * Service account token (Viewer role) ### Steps to Obtain Credentials {% stepper %} {% step %} #### Ensure you have permission Ensure you have a Grafana account with permission to create and edit service accounts. {% endstep %} {% step %} #### Navigate to Administration Sign in to Grafana and click "Administration" in the left-side menu. {% endstep %} {% step %} #### Add a service account Navigate to "Users and access" > "Service accounts" > "Add service account" {% endstep %} {% step %} #### Create the service account Enter a Display name, assign the "Viewer" role from the dropdown, and click "Create". {% endstep %} {% step %} #### Generate the token Click "Add service account token", enter a name for the token, and click "Generate token". {% endstep %} {% step %} #### Note down the token value Note down the token value for use in the Cleric web app. {% endstep %} {% endstepper %} ### What This Enables With Grafana connected, Cleric can query metrics and analyze dashboards: {% code overflow="wrap" %} ``` Query Grafana metrics for API response time over the last hour Check the system-overview Grafana dashboard for anomalies Show me Loki logs for errors in checkout-service What alert rules are currently firing in Grafana? Compare current memory usage to baseline using Grafana metrics ``` {% endcode %} Cleric uses Grafana to access metrics from Prometheus, Loki logs, and dashboard configurations, helping correlate visual dashboard insights with investigation findings. ## Honeycomb Connect Honeycomb to let Cleric read your **triggers**, the alert definitions in a Honeycomb environment, and optionally **query your data**. This lets Cleric tell what condition an alert actually watches, how it is evaluated, and who it pages, and check the data behind it. ### Prerequisites * A Honeycomb team with the environment you want Cleric to read * Permission to create API keys in that environment (Honeycomb **Owner** or **Manager**) ### Required Information * **Base API URL**: US (`https://api.honeycomb.io`) or EU (`https://api.eu1.honeycomb.io`) * A Honeycomb **Configuration key** for that environment, with the **Triggers** permission enabled (see Steps below) {% hint style="info" %} **Use a team-owned key, not a personal one.** Configuration keys created under **Environment settings > API keys** belong to the environment, so they keep working when a team member leaves. {% endhint %} ### Permissions Honeycomb's permission model does not offer a read-only variant of trigger access. The **Triggers** permission grants full create/read/edit/delete access to the Triggers API, so Cleric requires it even though Cleric only ever reads. Cleric compensates by refusing over-privileged keys. Connecting fails if the key carries **any** permission other than: | Checkbox in Honeycomb | Section | Required? | Why Cleric needs it | | ----------------------- | ------------------------------ | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Triggers** | Create, Read, Edit, and Delete | Yes | The only permission Honeycomb offers for reading triggers (grants create/read/edit/delete) | | **Manage datasets** | Data | Optional | Honeycomb also gates *listing* dataset names behind it. Grant it if you want Cleric to discover your datasets automatically; without it, Cleric reads environment-wide triggers and any dataset it can name from the alert | | **Queries and columns** | Create, Read, Edit, and Delete | Optional | Lets Cleric read and create query definitions and read saved queries. Honeycomb also requires it alongside **Run queries** to execute queries and retrieve results. Cleric never edits columns, calculated fields, or query annotations | | **Run queries** | Data | Optional | Lets Cleric query your data, such as rerunning the query behind a trigger. Honeycomb offers it on Enterprise plans only | Ingest keys and Management keys are rejected because they cannot read triggers. ### Supported and Unsupported APIs Cleric calls the Honeycomb API v1: * **Key introspection**: `GET /1/auth` (verifies the key and resolves the team and environment) * **Datasets**: `GET /1/datasets` (only if **Manage datasets** is granted; used to discover dataset names) * **Triggers**: `GET /1/triggers/{dataset}` and `GET /1/triggers/__all__` * **Query definitions and saved queries** (requires **Queries and columns**): * `POST /1/queries/{dataset}` and `GET /1/queries/{dataset}/{id}` (create a query from a specification, or read one by ID) * `GET /1/query_annotations/{dataset}` and `GET /1/query_annotations/{dataset}/{id}` (read the team's saved, named queries) * **Query data** (requires both **Queries and columns** and **Run queries**): * `POST /1/query_results/{dataset}` and `GET /1/query_results/{dataset}/{id}` (run a query and read its results) Cleric never creates, edits, disables, or deletes triggers, never edits columns, calculated fields, or query annotations, and does not send events or read Boards, SLOs, or Markers. ### Steps to Configure {% stepper %} {% step %} #### Create a Configuration key * In Honeycomb, go to **Environment settings > API keys** for the environment you want Cleric to read. * Create a new **Configuration** key named `Cleric`. * Enable **Triggers** under "Create, Read, Edit, and Delete", and optionally **Manage datasets** under "Data". * To let Cleric query your data, also enable **Queries and columns** under "Create, Read, Edit, and Delete" and **Run queries** under "Data". **Run queries** is only available on Honeycomb Enterprise plans. * Leave every other permission off. Cleric rejects keys with extra permissions. * Copy the key value. {% endstep %} {% step %} #### Configure the integration in Cleric * In the Cleric Web app, navigate to **Integrations** > **Honeycomb**. * Click **Add connection**. * Select the **Base API URL** (US or EU) and paste the **Configuration API Key**. * Click **Save connection** to verify access. {% endstep %} {% endstepper %} ### What This Enables With Honeycomb connected, Cleric can explain the alert it is investigating instead of guessing at it. This includes the query behind the trigger, the threshold that was crossed, how often it evaluates, and which alerts cover a service. With **Queries and columns** and **Run queries** enabled, Cleric can also rerun a trigger's query to see which groups crossed the threshold, and query your data around the alert. {% code overflow="wrap" %} ``` What does this Honeycomb alert actually measure? Which Honeycomb triggers are firing right now? What is the threshold on the checkout latency trigger, and how often is it evaluated? Which Honeycomb triggers cover the payments dataset? Which groups pushed the queue errors trigger over its threshold? ``` {% endcode %} Cleric cannot read raw events or change any Honeycomb configuration. Without **Run queries**, it can still read triggers and, with **Queries and columns**, query definitions and saved queries. ## incident.io Connect incident.io so Cleric can use current and past incidents, updates, alerts, follow-ups, and service ownership to inform an investigation. When you ask, Cleric can add an update or alert note, link its investigation, create a follow-up, or import a post-incident document. ### Permissions {% hint style="info" %} Create an organization API key named **Cleric** so updates it posts appear under Cleric's name in incident.io. You need permission to create API keys under **Settings → API keys**. {% endhint %} Under **Account-level permissions** in incident.io, select: * **View data, like public incidents and organization settings** * **Edit incidents** * **View all incident data, including private incidents** * **View catalog types and entries** * **View on-call resources like alerts, escalations and schedules** * **Manage postmortems, including updating its status** * **View incident participant workload** * **View incident participant workload, including for private incidents** If the key is missing access, Cleric tells you when you save the connection. Cleric can add information to an incident when you ask it to. It cannot declare or close incidents or change their status, severity, or summary. ### Steps to Configure {% stepper %} {% step %} #### Create an API key * In incident.io, open **Settings → API keys** and click **Add new**. * Name the key **Cleric** and select the eight account-level permissions listed above. * Copy the key when it is shown. incident.io displays it only once. {% endstep %} {% step %} #### Configure the integration in Cleric * In the Cleric Web app, navigate to **Integrations → incident.io**. * Click **Add connection** and paste the **API Key**. * Click **Save connection**. {% endstep %} {% endstepper %} ### What This Enables For example, you can ask Cleric: {% code overflow="wrap" %} ``` Is there already an incident for this checkout latency alert? How was INC-742 resolved? Which team owns payments-gateway? Post a summary of this investigation to INC-742 and link it there Create a follow-up on INC-742 for the connection pool fix, assigned to the Payments team ``` {% endcode %} ## Kubernetes ### How it Works The Kubernetes integration uses a service account with read-only RBAC permissions to access cluster resources, events, and pod logs. Cleric authenticates using a long-lived bearer token and communicates directly with the Kubernetes API server. The default ClusterRole also grants read access to common add-ons. This is how Cleric works with Argo CD: it reads Argo CD Applications and Argo Rollouts (the `argoproj.io` API group) through the Kubernetes API to check sync and rollout state. There is no separate Argo CD integration, and Cleric does not call the Argo CD API or CLI. If your Kubernetes control plane is public, you have the option to request Cleric provide specific IP addresses to allowlist. These IPs are assigned during provisioning, and all Cleric traffic originates from this CIDR range. For private clusters, see [Connecting Private Resources](/integrations/private-resources). > **EKS Users:** For Amazon EKS clusters, we offer a native integration that uses IAM authentication instead of long-lived tokens. See the [Elastic Kubernetes Service](#elastic-kubernetes-service) integration for details. ### Required Information * Kubernetes API server address * Kubernetes bearer token * Kubernetes CA certificate, only if a public CA did not sign the API server's certificate (as with most self-managed clusters) ### Steps to Obtain Credentials {% stepper %} {% step %} #### Ensure kubectl is configured Ensure you have access to a Kubernetes cluster and that `kubectl` is configured to interact with it. {% endstep %} {% step %} #### Run the configuration commands Run the following commands in your terminal: {% code overflow="wrap" expandable="true" %} ```shell # Create the namespace and a service account for Cleric kubectl apply -f - < **Note:** The built-in [`view` ClusterRole](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#default-roles-and-role-bindings) grants read-only access to most resources but **does not** allow reading Secrets, Roles, or RoleBindings. ### What This Enables With Kubernetes connected, Cleric can investigate cluster resources, pod issues, and deployments: {% code overflow="wrap" %} ``` Why is pod checkout-service-abc123 crashing? List all pods with high memory usage in production What changed in the api-gateway deployment in the last hour? Show me pods that have restarted more than 5 times today Check if there are any pending pods or resource quota issues What events occurred in the production namespace since 2pm? ``` {% endcode %} Cleric analyzes pod logs, events, resource utilization, and configuration to diagnose issues like OOMKills, CrashLoopBackOffs, failed deployments, and scaling problems. ## Langfuse Cleric can read your LLM application's traces, observations and scores from [Langfuse](https://langfuse.com) when it investigates an alert. ### Prerequisites * A project on Langfuse Cloud: EU, US, Japan or HIPAA. Self-hosted Langfuse isn't supported yet. * Permission to create API keys in that project. ### Required Information * **Region**: where your Langfuse project lives. * **Public Key** and **Secret Key**: a project's API keys with **Viewer** permissions. Please do not give Cleric keys with **Full access**: they can also send and delete data. Cleric will reject them for safety, and it will also turn down **Ingestion** keys, organization keys and keys that can't read the project's traces. One pair of keys covers one project. To add a second project, add a second Langfuse connection. **Note:** Cleric never sends, changes or deletes traces, scores, datasets or prompts. Its requests count toward your Langfuse API rate limits. ### Steps to Configure {% stepper %} {% step %} #### Create read-only API keys In your Langfuse project, open **Settings** > **API Keys** and click **Create new API keys**. Enter a **Name** such as `cleric`, set **Permissions** to **Viewer** and create the key. Copy the **Secret Key** now: Langfuse won't show it again. {% endstep %} {% step %} #### Configure the integration in Cleric In Cleric, open **Integrations** > **Langfuse**, click **Add connection**, pick the **Region**, paste both keys and click **Save connection**. Cleric checks the keys before it saves. {% endstep %} {% endstepper %} ### What This Enables Ask Cleric things like: * Which LLM calls in the support agent failed in the last hour, and with what error? * Why did the checkout assistant's latency go up after 14:00? * How much did the summarizer cost yesterday, and which model drove it? ## LaunchDarkly Connect LaunchDarkly to let Cleric check feature flag and segment changes. When it verifies a release or investigates an alert, Cleric can confirm whether a flag change was applied in an environment and when, what the flag serves now, and whether the new variation is actually being served. ### Prerequisites * A LaunchDarkly API token with the **Reader** role. Cleric rejects tokens with any other role, a custom role, or an inline policy. * Use a **service token**. If your plan doesn't offer service tokens, use a Reader personal token created by a dedicated member, such as a shared service account, because a personal token stops working when its member leaves your organization. ### Required Information * **Region**: Commercial (`app.launchdarkly.com`), EU (`app.eu.launchdarkly.com`) or Federal (`app.launchdarkly.us`) * **API Token**: a Reader token (see Prerequisites) ### Supported and Unsupported APIs Cleric reads from the LaunchDarkly REST API (`/api/v2`): * **Token check**: `GET /api/v2/caller-identity` and `GET /api/v2/tokens/{id}`, to confirm the token has the Reader role * **Audit log**: `GET /api/v2/auditlog`, for flag, segment and experiment changes * **Feature flags**: `GET /api/v2/flags/{projectKey}/{featureFlagKey}`, for targeting, rules, rollouts and variations * **Flag search**: `GET /api/v2/flags/{projectKey}`, to find a flag by part of its key, name or description * **Segments**: `GET /api/v2/segments/{projectKey}/{environmentKey}/{segmentKey}` * **Projects and environments**: `GET /api/v2/projects` * **Experiments**: `GET /api/v2/projects/{projectKey}/environments/{environmentKey}/experiments` * **Approval requests**: `GET /api/v2/approval-requests` and `GET /api/v2/approval-requests/{id}`, for flag and segment change requests * **Evaluation usage** (beta; may not be available on every LaunchDarkly plan): `GET /api/v2/usage/evaluations/{projectKey}/{environmentKey}/{featureFlagKey}`, for which variations are being served * **SDK connections** (beta; may not be available on every LaunchDarkly plan): `GET /api/v2/usage/service-connections`, for whether server-side SDKs are connected to an environment * **LaunchDarkly status page**: `status.launchdarkly.com/api/v2/incidents.json`, for LaunchDarkly's own incidents. It is public, and Cleric sends no token to it. Cleric is **read-only**: it never toggles flags, changes targeting, or edits segments, and it does not use SDK keys. ### Steps to Configure {% stepper %} {% step %} #### Create a Reader service token * In LaunchDarkly, open [**Create token**](https://app.launchdarkly.com/settings/authorization/tokens/new) (**Settings** > **Authorization** > **Tokens** > **Create token**). For EU or Federal accounts, use the same path on `app.eu.launchdarkly.com` or `app.launchdarkly.us`. * Enter a **Name** such as `Cleric`, select **Reader** in the **Role** menu, leave **Expiration** at **No expiration** and **API version** at its default, and select the **This is a service token** checkbox. * Click **Save token**, then copy the token. LaunchDarkly hides it after you leave the page. {% endstep %} {% step %} #### Configure the integration in Cleric * In the Cleric Web app, navigate to **Integrations** > **LaunchDarkly**. * Click **Add connection**. * Select your **Region** and enter the **API Token**. * Click **Save connection**. Cleric checks that the token has the Reader role before saving. {% endstep %} {% endstepper %} ### What This Enables With LaunchDarkly connected, Cleric can tie a release or an alert to the flag changes around it. {% code overflow="wrap" %} ``` Was the approved change to the checkout-v2 flag applied in production, and when? What does the new-pricing flag serve in production now, rule by rule? How large is the beta-testers segment, and what are its rules? Is the new variation of the search-ranking flag actually being served since the rollout? ``` {% endcode %} ## Logfire Cleric can read traces, logs and metrics from [Pydantic Logfire](https://pydantic.dev/logfire) when it investigates an alert. ### Prerequisites * A project on Logfire Cloud, US or EU. Self-hosted Logfire isn't supported yet. * Permission to create API keys in that project. ### Required Information * **API Key**: a project key with only **Read-only access**. Its prefix tells Cleric the region. Please do not give Cleric keys any permission beyond read, like **Send telemetry** or **Manage project and org**. It will reject those keys for safety and will also turn down organization keys, and keys that can't run a query. One key should cover a project. If you want to add a second project, add a second Pydantic connection. **Note:** Cleric never creates or changes dashboards, alerts, notification channels or managed variables. Its queries count toward your Logfire query limits. ### Steps to Configure {% stepper %} {% step %} #### Create a read-only API key In your Logfire project, open **Settings** > **API keys** and create a key. Tick only **Read-only access**, set **Key type** to **Project**, pick the project and click **Create API key**. Copy it now: Logfire won't show it again. {% endstep %} {% step %} #### Configure the integration in Cleric In Cleric, open **Integrations** > **Logfire**, click **Add connection**, paste the key and click **Save connection**. Cleric checks the key before it saves. {% endstep %} {% endstepper %} ### What This Enables Ask Cleric things like: * Which checkout spans failed in the last hour, and what did they throw? * Why did p95 latency on POST /orders go up after 14:00? * Show me the trace for the 500 at 09:12. ## Linear Connect Linear to let Cleric file issues, comment on existing ones, and read your team's backlog during investigations. Cleric appears as a real, non-billable member of your Linear workspace; issues and comments it creates are attributed to **Cleric**, not to whoever installed the integration. ### How it Works Linear uses an OAuth 2.0 install flow. You authorize the shared Cleric Linear app, choose the workspace to install into, and Cleric receives a workspace-scoped access token plus a refresh token. The access token is rotated automatically; both tokens are stored encrypted in your Cleric instance and can be revoked at any time from Linear's **Settings → API → Applications** page. The OAuth grant requests these scopes: * `read`: read issues, projects, teams, and comments * `issues:create`: create new issues * `comments:create`: add comments to issues Cleric joins your workspace as a non-billable bot member. Linear doesn't count it against your seat count. ### Steps to Configure {% stepper %} {% step %} #### Start the install In the Cleric Web app, go to **Integrations → Linear** and click "Connect Linear". You will be redirected to Linear's consent screen. {% endstep %} {% step %} #### Approve the install On Linear's consent screen, choose the workspace you want Cleric to install into. Workspace admins approve once; subsequent users do not need to re-consent. {% endstep %} {% step %} #### Confirmation When the flow completes, you are redirected back to Cleric and the workspace appears in the Linear integration list. {% endstep %} {% endstepper %} ### What This Enables Cleric can search and read issues, comment on them, and file new issues when responding to investigations. Example uses: {% code overflow="wrap" %} ``` @Cleric File a Linear issue for this OOM incident in the ENG team's backlog @Cleric What's the status of LIN-1234? @Cleric Add a comment summarizing this investigation to LIN-1234 ``` {% endcode %} ### Disconnecting Removing the Linear integration from Cleric's **Integrations** page immediately cuts Cleric's access to your workspace. The "Cleric" app entry stays in Linear's **Settings → API → Applications** until a workspace admin removes it there. Doing so isn't required for security (access is already gone), only for tidiness. ## MongoDB Atlas ### Required Information * Atlas Project ID (also called Group ID) * Atlas API public key * Atlas API private key ### How it Works Cleric connects to the [MongoDB Atlas Administration API](https://www.mongodb.com/docs/atlas/reference/api-resources-spec/v2/) using HTTP Digest Authentication with an API key pair. During investigations, Cleric can retrieve slow query logs, process-level metrics (CPU, connections, opcounters), and database process logs to diagnose performance issues. To restrict Cleric to operational data only (metrics, slow query logs, process logs) without access to database contents, assign the **Project Read Only** and **Project Observability Viewer** roles. Do not assign **Project Data Access Read Only** or any other data access role. {% hint style="info" %} **Tier limitations:** Slow query logs require M10+ clusters (not available on M0/M2/M5 free and shared tiers). Metrics and process logs are available on all tiers, though some metrics (WiredTiger tickets, replication lag, query targeting) require M10+. {% endhint %} ### Steps to Configure {% stepper %} {% step %} #### Find your Atlas Project ID 1. Log in to [MongoDB Atlas](https://cloud.mongodb.com) 2. Select your project 3. Go to **Project Settings** (gear icon in the left sidebar) 4. Copy the **Project ID** (a 24-character hex string) {% endstep %} {% step %} #### Create an API key 1. In Atlas, go to **Organization** > **Access Manager** > **API Keys** 2. Click **Create API Key** 3. Set a description (e.g., "Cleric Integration") 4. Assign the **Project Read Only** and **Project Observability Viewer** roles. Do not assign Data Access roles. Cleric only needs performance analytics, not access to database contents. 5. Click **Next** 6. Copy the **Public Key** and **Private Key** (the private key is only shown once) {% endstep %} {% step %} #### Add Cleric's IP to the API key access list Atlas API keys require an IP access list. Add Cleric's outbound IP address to allow API access: 1. On the API key page, under **API Access List**, click **Add Access List Entry** 2. Add Cleric's outbound IP address (check your Cleric instance's network configuration) 3. Click **Save** Without this step, all API calls will return 401 regardless of key validity. {% endstep %} {% step %} #### Add to Cleric In the Cleric Web app, go to **Integrations** > **MongoDB Atlas** > **Add connection**. Enter your Project ID, public key, and private key, then click **Save connection**. Cleric will validate the connection before saving. {% endstep %} {% endstepper %} ### What This Enables With MongoDB Atlas connected, Cleric can analyze database performance and cluster health: {% code overflow="wrap" %} ``` Check MongoDB Atlas for slow queries in the last hour What are the current connection counts and CPU usage on the Atlas cluster? Show me the MongoDB process logs around the time of the incident Are there any collection scans or missing indexes causing slow queries? What's the replication lag on the Atlas cluster secondaries? ``` {% endcode %} Cleric retrieves slow query logs from the Performance Advisor, fetches process-level metrics (connections, CPU, opcounters, WiredTiger cache), and analyzes database logs to identify performance bottlenecks like missing indexes, collection scans, and connection storms. ## New Relic Connect New Relic to let Cleric query logs, metrics, traces, alerts, and entities using NerdGraph (GraphQL) and NRQL. ### Prerequisites * A New Relic account with **Full Platform** user type * A **User API Key** (starts with `NRAK-`) * Your **Account ID** ### Steps to Configure {% stepper %} {% step %} #### Create a User API Key * Log in to New Relic and navigate to your profile (bottom-left) > **API Keys** * Click **Create a key**, select **User** as the key type * Give it a descriptive name (e.g., "Cleric Integration") * Copy the key immediately. It is only shown once. {% endstep %} {% step %} #### Find your Account ID * In the New Relic UI, your Account ID appears in the URL or under **Administration** > **Access Management** {% endstep %} {% step %} #### Configure the integration in Cleric * In the Cleric Web app, navigate to **Integrations** > **New Relic** * Click **Add connection** * Select your **API Endpoint** (US or EU) * Enter your Account ID and User API Key * Click **Save connection** to verify access {% endstep %} {% endstepper %} ### What This Enables With New Relic connected, Cleric can query all telemetry data in your account using NRQL via the NerdGraph GraphQL API: {% code overflow="wrap" %} ``` Show me the error rate for the checkout service over the last hour What alert incidents fired in the last 2 hours? Show the p95 latency for all services, broken down by transaction name Find all ERROR logs from the payment service around the time of the incident ``` {% endcode %} ## Notion Connect Notion to let Cleric search your runbooks, postmortems, and knowledge-base pages during investigations. Cleric receives read-only access to the pages you explicitly share with the integration. ### How it Works Notion uses an OAuth 2.0 install flow. You authorize the shared Cleric Notion app, select which pages to share, and Cleric receives a workspace-scoped access token. The token is stored encrypted in your Cleric instance and can be revoked at any time from Notion's **Connections** UI. The integration is configured with the **Read content** capability only. Cleric cannot create, update, or delete Notion content. ### Steps to Configure {% stepper %} {% step %} #### Start the install In the Cleric Web app, go to **Integrations → Notion** and click "Connect Notion". You will be redirected to Notion's consent screen. {% endstep %} {% step %} #### Approve and choose what to share On Notion's consent screen, choose the workspace and pick what Cleric should see. You can share an entire teamspace, a top-level page, or individual pages or databases. Anything nested inside what you pick is included automatically. You can change this later (see [Sharing more pages later](#sharing-more-pages-later)). {% endstep %} {% step %} #### Confirmation When the flow completes, you are redirected back to Cleric and the workspace appears in the Notion integration list. {% endstep %} {% endstepper %} ### What This Enables During investigations Cleric can search and read the Notion pages you shared during install (and anything nested inside them). Pages outside that scope are invisible to Cleric. See [Sharing more pages later](#sharing-more-pages-later) if you want to expand or narrow what Cleric can read. Example uses: {% code overflow="wrap" %} ``` @Cleric Find the runbook for high checkout-service error rates @Cleric What does the on-call rotation page say about escalation? ``` {% endcode %} ### Sharing more pages later All of these steps happen inside Notion. Cleric picks the change up automatically. **Share one specific page.** Open the page in Notion, click the **`···`** menu in the top-right corner, scroll to the **Connections** section, and pick **Cleric**. Anything nested inside that page is shared too. **Edit the full list of shared pages.** In Notion, go to **Settings → Connections → Installed**, click **Cleric**, then under **Access** click **Select pages**. From there you can add or remove teamspaces, top-level pages, or individual pages and databases. ### Enterprise workspaces Enterprise Notion admins can restrict which third-party integrations are connectable via the workspace's **approved connections** list. If "Connect Notion" fails for non-admin users, ask your Notion admin to approve the Cleric integration for your workspace. ### Disconnecting Removing the Notion integration from Cleric's **Integrations** page immediately cuts Cleric's access to your workspace. Unlike Slack, Notion doesn't let an app remove itself from a workspace. The "Cleric" entry stays in Notion's **Settings → Connections** until you remove it there yourself. Doing so isn't required for security (access is already gone), only for tidiness. ## PagerDuty ### Required Information * PagerDuty API token * PagerDuty API URL (select your region from the dropdown: US or EU) ### Steps to Obtain Credentials #### Log in to your PagerDuty account #### Navigate to API Access Keys Navigate to "Integrations" > "API Access Keys" under Developer Tools #### Create a new API key Click "Create New API Key" #### Enter a description Enter a Description to help you identify the key later #### Create the key Click "Create Key" #### Copy the API token Copy the generated API token (Note: This is the only time you'll see the full key) #### Add to Cleric In the Cleric Web app, go to **Integrations** > **PagerDuty** > **Add connection**. Enter your API token and select your API URL from the dropdown: | Region | API URL | | ------ | ------------------------------ | | US | `https://api.pagerduty.com` | | EU | `https://api.eu.pagerduty.com` | ``` {% endstep %} {% endstepper %} ``` ### What This Enables With PagerDuty connected, Cleric can analyze incident context and on-call patterns: {% code overflow="wrap" %} ``` What incidents are currently open in PagerDuty? Show me details for PagerDuty incident #12345 What services have had the most incidents this week? How many times has the checkout-service alerting policy triggered today? ``` {% endcode %} Cleric uses PagerDuty data to understand alert patterns, incident frequency, and service health trends, helping identify recurring issues and improve alerting effectiveness. ## Prometheus ### Required Information * Prometheus server URL * Authentication credentials (if enabled) * Prometheus type (Prometheus, VictoriaMetrics Single, or VictoriaMetrics Cluster) Cleric only reads from Prometheus; it never writes or uses the admin API. ### Steps to Obtain Credentials {% stepper %} {% step %} #### Ensure you have access Ensure you have access to a Prometheus server or VictoriaMetrics instance {% endstep %} {% step %} #### Note down the following information * Server URL (e.g., "") * If basic auth is enabled: * Username * Password * Prometheus type: * `prometheus` for standard Prometheus installations * `victoriametrics_single` for single-node VictoriaMetrics * `victoriametrics_cluster` for clustered VictoriaMetrics {% endstep %} {% endstepper %} ### What This Enables With Prometheus connected, Cleric can query metrics and alert rules: {% code overflow="wrap" %} ``` Query Prometheus for CPU usage spikes in the last 2 hours What's the P95 API response time trend since midnight? Show me all firing Prometheus alerts Compare current memory usage to baseline from last week What metrics show anomalies correlated with the API latency increase? ``` {% endcode %} Cleric uses Prometheus to analyze resource utilization, application performance, and alert states, helping identify trends and correlations that explain production issues. ## Raindrop Cleric can read events, traces and signals from [Raindrop](https://www.raindrop.ai) when it investigates an alert about your AI product. ### Prerequisites * Access to the Raindrop Query API. It is in beta; ask to turn it on for your organization. * Permission to create API keys in your Raindrop organization. ### Required Information * **Query API Key**: an org-wide Query SDK key. Please use an org-wide key, not a personal key: a personal key follows its owner's role and stops working when they leave. Org-wide keys expire, so replace the key in Cleric before it does. Raindrop keys can't be limited to reading, so Cleric's instructions keep it to reads. **Note:** Cleric never requests user-data deletion and never sends events. Its queries count toward your Raindrop rate limits. ### Steps to Configure {% stepper %} {% step %} #### Create an org-wide key In Raindrop, open **Settings** > **API Keys**. Under **Query SDK**, click **Create org-wide key** and copy the key. {% endstep %} {% step %} #### Configure the integration in Cleric In Cleric, open **Integrations** > **Raindrop**, click **Add connection**, paste the key and click **Save connection**. Cleric checks that the key can read events before it saves. {% endstep %} {% endstepper %} ### What This Enables Ask Cleric things like: * Which conversations got a thumbs-down today, and what did the assistant say? * Which tool calls started failing after 14:00, and for which model? * Show me the trace for the support chat that failed at 09:12. ## Sentry ### Required Information * **Deployment**: Cloud or Self-hosted * **Base URL**: Required only for Self-hosted deployments * **Organization Slug** * Optional **Project Slug** * Sentry personal API token with these scopes: * `alerts:read` * `event:read` * `org:read` * `project:read` These scopes cover organization validation during setup plus project, issue, alert, and event investigation after the toolkit is connected. Cleric validates the token scopes during setup and rejects tokens that are missing any of these scopes or include additional scopes. ### Steps to Configure {% stepper %} {% step %} #### Create a read-only API token * In Sentry, open **Settings** > **Account** > **API** > **Auth Tokens** * Create a personal token with these scopes: * `alerts:read` * `event:read` * `org:read` * `project:read` * Copy the token value for the Cleric integration form {% endstep %} {% step %} #### Find your organization slug and optional default project slug * Open the target project in Sentry * Copy the organization slug from the URL * Optionally copy a project slug if you want Cleric to default to one project during investigations * If you use self-hosted Sentry, also copy the base URL of your instance {% endstep %} {% step %} #### Configure the integration in Cleric * In the Cleric Web app, navigate to **Integrations** > **Sentry** * Click **Add connection** * Select **Cloud** or **Self-hosted**. For Self-hosted, enter the **Base URL**, then enter the **Organization Slug**, optional **Project Slug**, and **API Token**. * Click **Save connection** to verify access {% endstep %} {% endstepper %} ### What This Enables With Sentry connected, Cleric can inspect issues, events, stack traces, releases, and project-level error patterns through the Sentry CLI. {% code overflow="wrap" %} ``` List the latest unresolved Sentry issues for the checkout project Show me the stack trace and latest events for Sentry issue 123456789 Check whether this spike started after a new release in Sentry ``` {% endcode %} ## Slite Connect Slite to let Cleric search and read runbooks, incident procedures, architecture notes, and other knowledge-base documentation during investigations. ### Prerequisites * A Slite workspace with Public API access * Permission to create a personal API key under **Settings → API** {% hint style="info" %} **The key must be read-only.** In Slite's **Create a new key** dialog, turn on the **Read-only** toggle before clicking **Confirm**. Do not leave this toggle off. Cleric tests that Slite denies write access before accepting the key. Never connect a read & write key. {% endhint %} ### Permissions Create a personal Slite API key with these settings: | Setting | Required value | Why | | -------------------- | ----------------------------------- | -------------------------------------------------------------------------------- | | **Read-only** toggle | **Enabled** | Slite enforces that the credential cannot call write endpoints | | Key owner access | Only the content Cleric should read | Personal keys inherit all note and channel access of the person who created them | Cleric authenticates the key through `GET /me`. Because Slite does not provide a REST endpoint that reports a key's scope, Cleric also sends a schema-invalid request to the write-scoped notes endpoint. This request cannot create a note. Cleric accepts the key only when Slite explicitly denies write access; write-enabled or ambiguous keys are rejected. On Enterprise, you may instead use a read-only key owned by a Restricted service account. Service-account keys are not tied to an employee and can be limited to explicitly shared channels and docs. ### Supported and Unsupported APIs Cleric uses the Slite Public API at `https://api.slite.com/v1` for: * Accessible note metadata and workspace browsing through `GET /notes` * Full-text note search through `GET /search-notes` * Note metadata and Markdown content through `GET /notes/{noteId}` * Authenticated workspace identity through `GET /me` Cleric does not connect to Slite MCP. During investigations, it does not use Slite Ask, comments, users or groups, knowledge-management reports, connected Agent sources, or any endpoint that creates, edits, moves, verifies, archives, restores, or deletes content. The connection-time permission check described above is the only call to a write-scoped endpoint, and its intentionally invalid payload cannot create content. Notes unavailable to the API key owner are invisible to Cleric. The Slite Public API rate limit is 120 calls per minute. Cleric honors `Retry-After` and retries a rate-limited read once. ### Steps to Configure {% stepper %} {% step %} #### Create a personal read-only key * In Slite, open **Settings → API** and click **Create a new key**. * In the **Create a new key** dialog, turn on the **Read-only** toggle, then click **Confirm**. The toggle must be enabled; do not create the key with it turned off. * Copy the key when it is shown. Slite displays it only once. {% endstep %} {% step %} #### Configure the integration in Cleric * In the Cleric Web app, navigate to **Integrations → Slite**. * Click **Add connection** and paste the **API Key**. * Click **Save connection**. * Cleric verifies the key, workspace identity, and denial of write access before accepting the configuration. {% endstep %} {% endstepper %} ### What This Enables With Slite connected, Cleric can bring operational documentation into an investigation: {% code overflow="wrap" %} ``` Find the Slite runbook for checkout latency alerts What does our database failover procedure say about promoting a replica? Compare this incident with the verified deployment rollback guide in Slite ``` {% endcode %} If a known note is missing, verify that the person who created the key can open that note. Because personal keys are tied to a user, replace the key if that person leaves the workspace. Enterprise customers can avoid that lifecycle dependency by using a Restricted service account. ## Splunk ### Required Information * Splunk management API URL (typically on port 8089) * Splunk username * Splunk password ### Steps to Configure {% stepper %} {% step %} #### Identify your Splunk management API URL The Splunk management API runs on port 8089 by default (e.g., `https://splunk.example.com:8089`). This is separate from the Splunk Web UI port (8000). If you're unsure, check your Splunk deployment settings or ask your Splunk administrator. {% endstep %} {% step %} #### Create a dedicated Splunk user with read-only access Cleric only needs permission to run searches. We recommend creating a dedicated user with a role scoped to the minimum required access. **Option A: Use the built-in `user` role** The built-in `user` role grants search access across all indexes the role can see, with no administrative or write permissions. This is the simplest option if you're comfortable with Cleric searching all default indexes. 1. In Splunk Web, go to **Settings** > **Users and Authentication** > **Users** 2. Click **New User** 3. Set a username (e.g., "cleric-readonly") and password 4. Assign the **user** role 5. Click **Save** **Option B: Create a custom role with restricted index access** If you want to limit which indexes Cleric can search: 1. Go to **Settings** > **Users and Authentication** > **Roles** > **New Role** 2. Name it (e.g., "cleric-integration") 3. Under **Inheritance**, select **user** as the parent role (this inherits basic search capabilities) 4. Under **Indexes**, select only the indexes you want Cleric to search in both "Indexes searched by default" and "Indexes" 5. Do not grant any additional capabilities beyond what the `user` role provides 6. Click **Save** 7. Create a new user (as in Option A) and assign this custom role instead of `user` {% endstep %} {% step %} #### Add to Cleric In the Cleric Web app, go to **Integrations** > **Splunk** > **Add connection**. Enter your management API URL, username, and password, then click **Save connection**. Cleric will validate the connection before saving. {% endstep %} {% endstepper %} ### What This Enables With Splunk connected, Cleric can search and analyze logs stored in Splunk: {% code overflow="wrap" %} ``` Search Splunk for errors related to the checkout service in the last hour Show me timeout errors across all indexes since midnight What are the most common error patterns in the payment-service logs? Find logs matching "connection refused" for the API gateway Search Splunk for trace ID abc123 across all services ``` {% endcode %} Cleric constructs Splunk search queries, retrieves matching log events, and correlates findings with other data sources to identify root causes and patterns across your infrastructure. ## Unleash Connect Unleash to let Cleric inspect feature flags, projects, environments, activation strategies, and change history so it can determine whether a feature flag was responsible for, or coincident with, an incident. ### Prerequisites * An Unleash instance (self-hosted or Unleash Cloud) reachable from Cleric * A **read-only token that can call the Admin API**. In Unleash, read-only is the **role of the identity** behind the token, not a setting on the token itself, so the token must belong to a **Viewer**. **Do not create a plain "Admin" API token**: that type is full read-write with no read-only option. Instead, on **Enterprise** create a **service account** with the **Viewer** root role and add an API token to it (recommended because it isn't tied to a person who might leave); on **Open Source**, create a **personal API token** while signed in as a user whose root role is **Viewer**. ### Required Information * **Deployment**: Cloud or Self-hosted * For Cloud, your Unleash **Instance ID** from `https://.app.unleash-hosted.com/` * For Self-hosted, your Unleash **Base URL** (for example, `https://unleash.example.com`) without `/api` * An Unleash **API token** belonging to a **Viewer** identity (a Viewer service account, or a Viewer user's personal API token). See Prerequisites. ### Supported and Unsupported APIs Cleric reads from the Unleash **Admin API** (`/api/admin`): * **Projects**: `GET /api/admin/projects` * **Feature flags** (with per-environment state and strategies): `GET /api/admin/projects/{projectId}/features` and `.../features/{flagName}` * **Environments**: `GET /api/admin/environments` * **Change/event history**: `GET /api/admin/events` (latest 100, or all events for a project via `?project=`) and the paginated `GET /api/admin/search/events` (`offset`/`limit`, `from`/`to`, `project`, `feature`, `type`) Cleric is **read-only**: it never toggles flags, edits strategies, or changes environments, and it does not read the Frontend or Client SDK APIs. ### Steps to Configure {% stepper %} {% step %} #### Create a read-only API token The token's access is determined by the **role of the identity** it belongs to, not by a setting on the token. Do **not** create a plain "Admin" API token. That type is full read-write and offers no read-only option. Create the token against a **Viewer** identity instead: * **Enterprise (recommended):** go to **Admin settings > Service accounts**, create a service account with the **Viewer** root role, then add an **API token** to it. A service account isn't tied to a person, so the token keeps working when team members leave. * **Open Source:** sign in as a user whose root role is **Viewer**, open **Profile > Personal API tokens**, and create a token (it inherits that user's read-only permissions). * Copy the token value. {% endstep %} {% step %} #### Find your instance URL * Copy the base URL of your Unleash instance from your browser (e.g. `https://unleash.example.com`). Remove any trailing `/api` or path. {% endstep %} {% step %} #### Configure the integration in Cleric * In the Cleric Web app, navigate to **Integrations** > **Unleash**. * Click **Add connection**. * Select **Cloud** or **Self-hosted**. For Cloud, select the region and enter the **Instance ID**. For Self-hosted, enter the **Base URL**. Then enter the **API Token**. * Click **Save connection** to verify access. {% endstep %} {% endstepper %} ### What This Enables With Unleash connected, Cleric can correlate incidents with feature-flag changes. This includes finding which flags are enabled in the affected environment, what traffic their strategies actually target, and when they last changed. {% code overflow="wrap" %} ``` Was any feature flag toggled in production right before this incident? Is the checkout-v2 flag enabled in production, and what rollout percentage is it on? Show me the change history for the new-pricing flag Which flags changed in the payments project in the last 2 hours? ``` {% endcode %} Cleric reads Unleash through the Admin REST API only. Flag state is reported per environment, and Cleric inspects activation strategies so it distinguishes "enabled for everyone" from "enabled for a slice of traffic". # Connecting Private Resources Connect Cleric to resources in private networks Cleric provides a lightweight Connector that you deploy inside your private network (on a VM or inside Kubernetes). The Connector functions as a simple network proxy, allowing Cleric to query your private endpoints, such as your Kubernetes API servers. ## How It Works You configure what Cleric can access by providing configuration to the Connector. Cleric cannot reach any part of your network beyond the endpoints you configure. The Connector creates a secure connection from your private environment to ours. No public IPs, VPN appliances, or special firewall rules required. The connection is end-to-end encrypted, ensuring that your data stays protected. ## Use Cases Common scenarios for the Connector include: * **Private Kubernetes clusters**: Access clusters without public API server endpoints * **Internal monitoring systems**: Connect to Prometheus, Grafana, or other tools behind a firewall * **On-premises infrastructure**: Query resources in data centers not exposed to the internet ## Getting Started Connector deployment is guided by the Cleric team. Reach out via your dedicated Slack Connect channel to set up private resource access for your environment. # MCP Server Work with Cleric issues, changes, the service catalog, and usage, and connect integrations, from MCP clients Cleric exposes a [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that lets coding agents work with your Cleric data: issues with their root cause, evidence, and proposed fixes; changes Cleric verified after deploy; the service catalog and its dependency map; the knowledge base; and usage stats. A coding agent can also start an investigation, follow up on one, and connect your tools. Your agent needs this guide, your instance URL, and a personal Cleric API key. ## Getting Your API Key 1. Open **Settings** in the Cleric web app (`.app.cleric.ai`) and select the **Personal** tab. 2. Under **Personal API key**, click **Generate API key**. 3. In the **API key created** dialog, click **Copy**, and store the key securely. The dialog will not be shown again. 4. Use the key as the Bearer token in your MCP client config (see below). {% hint style="warning" %} This is your personal API key. It authenticates as your user account, and any actions taken through the MCP server are attributed to you. Do not share it with other users or commit it to source control: each user should generate their own key. {% endhint %} You can only have one API key configured per user at a time. To rotate it, click **Revoke** on the existing key, confirm, then **Generate API key** again. Any MCP client configurations using the old key will stop working immediately on revoke. ## Setup ### Claude Code Add a `.mcp.json` file to your project root (or `~/.claude.json` for global config): ```json { "mcpServers": { "cleric": { "type": "http", "url": "https://.app.cleric.ai/mcp", "headers": { "Authorization": "Bearer ${CLERIC_API_KEY}" } } } } ``` Set the environment variable with your API key. `read -s` keeps the key out of your shell history; paste it at the prompt: ```bash read -rs CLERIC_API_KEY && export CLERIC_API_KEY ``` Restart Claude Code after adding the configuration. You should see Cleric listed as a connected MCP server. {% hint style="info" %} Using `${CLERIC_API_KEY}` keeps the key out of files that might be committed to version control. You can also replace it with the literal key value if you prefer. {% endhint %} ### Codex Add the server, reading the key from `CLERIC_API_KEY` each time Codex starts: ```bash codex mcp add cleric --url https://.app.cleric.ai/mcp --bearer-token-env-var CLERIC_API_KEY ``` Codex does not show MCP prompts, so ask it in words. Codex asks you to approve each Cleric tool call that changes something, such as creating a connection. ### Cursor Add the server to `~/.cursor/mcp.json`, which stays out of your repositories: ```json { "mcpServers": { "cleric": { "type": "http", "url": "https://.app.cleric.ai/mcp", "headers": { "Authorization": "Bearer ${env:CLERIC_API_KEY}" } } } } ``` Alternatively, add the server through **Cursor Settings > MCP** using the URL and headers above. ## Available Tools Once connected, the following tools are available to the AI assistant. The server returns only what your user can see in the web app: issues and changes from private Slack channels you are not a member of are hidden. | Tool | Description | | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `list_issues` | List issues, most recently occurring first. Merged duplicates are rolled into their issue. Filter by `status` (`investigating`, `suggested_fix`, `inconclusive`, `pending_verification`, `resolved`), `service`, `resolved_reason` (`suggested_fix`, `other_fix`, `self_resolved`, `false_positive`), and `min_alert_count`. `sort` by `last_occurred_at` (default), `created_at`, or `alert_count`. `since` (default 7 days ago, at most 90) counts an issue when it or a duplicate merged into it occurred after that time. | | `get_issue` | Get one issue by slug (for example `ISS-123`) or ID: status, alert, Cleric's latest answer with citations, remediation actions with the current one marked, and the repository of the affected service when the service catalog knows it. `include` adds `hypotheses`, `occurrences`, and the thread (`timeline`). `wait_seconds` (up to 60) waits for a running investigation to finish. | | `search_issues` | Search issues by text. Returns keyword matches on the title, alert, and thread (default last 30 days), and on the first page, semantically similar issues from completed investigations seen in the last 30 days. | | `create_issue` | Start a new Cleric investigation. Pass a description of what to investigate. Uses credits, as an investigation started from the web app does. | | `follow_up` | Send a follow-up message to an issue's investigation, as if replying in its thread. | | `list_changes` | List changes Cleric tracked after deploy, newest first, with their verification status and, for anomalies, the issue Cleric opened. Filter by `author` (`me` or a GitHub login), `status`, `service`, and `since` (default 7 days ago). | | `get_change` | Get one change by slug (for example `CHG-123`): intent, release, links, and every expectation Cleric is verifying with its status and evidence summary. | | `get_service` | Look up a service in the service catalog: where it runs, its source repository, and the services it depends on or is depended on by, up to 3 hops. | | `search_knowledge` | Search Cleric's knowledge base (facts learned from past incidents, Slack discussions, and ingested docs/runbooks) for information relevant to a query. | | `get_usage_stats` | Usage for the last 7 or 30 days and the period before: issue counts and outcomes as on the Performance page, result ratings, and active users. Counts only; no issue contents. | | `query_usage` | Credit usage, filtered and grouped like a SQL query. `where` filters by billing month range (`from_month`, `to_month`, from July 2026 to the current month, default the current month), `kind` (`issue`, `chat`, `release`, `change`), `channel`, `user`, and `item`. `group_by` takes up to 4 of `month`, `kind`, `channel`, `user`, and `item`. Each row reports credits, distinct items, and its share of the filtered total; grouping by `item` adds each item's title and link. | | `list_integration_schemas` | List the integrations available on your instance. Pass `toolkit_type` for one integration's configuration and credential JSON schemas, setup instructions and documentation link. | | `list_integration_connections` | List the connected integrations with what each points at and whether its last connection check passed. Credentials are never included. Pass `toolkit_type` for one integration. | | `create_integration_connection` | Test an integration with the supplied `configuration` and save it as a new connection if the test passes. Nothing is saved when validation or the test fails. An existing connection with the same name is never changed. | | `update_integration_connection` | Change a connection's `description`, `config` or `credentials`, or set `enabled`. Fields you omit keep their saved values. An enabled connection is tested first and nothing is saved if the test fails. | | `test_integration_connection` | Test a saved connection now instead of waiting for the hourly check, and return the provider's error if it fails. | | `delete_integration_connection` | Remove a connection and its credentials. This cannot be undone. | Limitations: * **Changes** exist only for deploys whose notification Cleric picked up and verified. A deploy Cleric did not see does not appear in `list_changes`. * **Service dependencies** come from discovery and can be incomplete. Managed databases and SaaS dependencies are often missing, and catalog data can be up to a day old. * **Alert counts** cover an issue's whole history, including duplicates merged into it, not just the `since` window. * **Usage by user** credits the person who started the thread. Alerts posted in Slack count against the bot that posted them, alerts received by webhook show as `(webhook alert)`, and follow-ups count against the thread's starter. Usage outside Slack shows channel `(web app)` for threads started in the web app and `(none)` for threads with no channel, such as webhook alerts. Usage in private Slack channels you are not a member of is counted in totals but shown as `(private)`, without its channel or item. ## Prompts The server also provides prompts for common workflows. Claude Code shows them as slash commands, for example `/mcp__cleric__fix_open_issues`. | Prompt | What it does | | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | | `fix_open_issues` | Works through open issues with a suggested fix and drafts each fix in the current repository. Takes `count` (default 5). | | `check_my_changes` | Checks whether changes you deployed caused problems Cleric detected, starting with unaddressed anomalies. Takes `days` (default 7). | | `find_noisy_alerts` | Finds alerts that fire often and resolve without action, and suggests how to tune them. Takes `days` (default 30). | | `weekly_usage_report` | Summarizes this week's Cleric usage against the previous week. | ## Connect an Integration Ask your coding agent to connect an integration: ``` Connect my Kubernetes cluster to Cleric as production-cluster, using the endpoint, CA certificate and read-only token I provide. ``` The agent calls `list_integration_connections` to see what is already connected, `list_integration_schemas` with `{"toolkit_type": "kubernetes"}` for the fields the integration takes and the link to its guide in [Supported Integrations](/integrations/supported-integrations), then `create_integration_connection`: ```json { "configuration": { "name": "production-cluster", "description": "Production Kubernetes", "toolkit_type": "kubernetes", "config": { "host": "https://kubernetes.example.com", "certificate_b64": "" }, "credentials": { "api_token": "" } } } ``` Cleric tests the connection with these credentials before saving it. `description` is optional and `enabled` defaults to `true`. Fields outside the schema are rejected, and so are fields the schema marks `readOnly`, such as the AWS `external_id`: Cleric fills those in. A field with a `prefix` or `suffix` in the schema, such as `https://` for a Kubernetes host, is completed with it when the value omits it. For private endpoints, complete [Connecting Private Resources](/integrations/private-resources) first. The test may provision firewall access and contacts the provider. The provider side of each integration, such as the service account, IAM role or API token Cleric needs, is in that integration's section of [Supported Integrations](/integrations/supported-integrations), linked as `docs_url` from `list_integration_schemas`. An agent with your cloud CLI can do that setup too. For AWS and EKS: 1. `list_integration_schemas` with `{"toolkit_type": "aws"}` returns, in `instructions_markdown`, the trust policy for your instance, including its external ID. The web app shows the same policy. 2. Create the IAM role with that trust policy, the validation policy from the [AWS guide](/integrations/supported-integrations#amazon-web-services), which lets Cleric verify the role is read-only, and the read-only policies you want. Add `eks:Describe*` and `eks:List*` for EKS. 3. `create_integration_connection` for `aws` with the role ARN and default region. The test assumes the role and fails if its policies grant write access. 4. For each EKS cluster, grant the role access to the cluster as a member of the `cleric` group and apply the `cleric-role` ClusterRole as in the [EKS guide](/integrations/supported-integrations#elastic-kubernetes-service), then `create_integration_connection` for `eks` with the cluster ARN and API server host. The AWS connection for the cluster's account must exist first; the EKS test authenticates through it. Common credential fields: | Integration | Configuration Fields | Credential Fields | | ----------- | --------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | | Kubernetes | `host`, `certificate_b64` (base64-encoded PEM CA certificate; optional for a public CA) | `api_token` | | Generic MCP | `url` (Streamable HTTP endpoint) | `authorization_header` (full header, such as `Authorization: Bearer `) | | Grafana | `host` | `api_token` | | Datadog | `host` | `api_key`, `app_key` | Use `list_integration_schemas` for the fields of other integrations. Give credentials to your agent through its secure local configuration, and keep them out of investigation descriptions and source control. Tool results never include submitted credentials. ### Handle Results A connection that is created returns what `list_integration_connections` reports for it, including what it points at and that its test passed. Otherwise the tool returns an error that says what to change: * **Invalid configuration** names each missing, unknown, read-only or invalid field, without its value. * **Connection failed** gives the provider's error, for example a rejected key, an unreachable endpoint, or an AWS role whose policies grant write access. * **Already exists** names the integration and endpoint of the existing connection. If it is the one you meant, the integration is already connected; otherwise choose another name. `list_integration_connections` reports each connection as `healthy` when its last connection check, run every hour, passed within the last two hours. After fixing access on the provider side, `test_integration_connection` re-tests it at once. To rotate a credential, `update_integration_connection` with only that credential field. Pointing a connection at a different endpoint needs every credential replaced; otherwise create a new connection. ### Provider Consent Integrations that need consent from the provider are connected in the web app: * **Slack:** a workspace administrator approves **Add to Slack**. * **GitHub:** install the Cleric GitHub app and approve repository access. To connect your own GitHub app instead, supply its `app_id`, `private_key_b64` and `installation_id`. * **Linear and Notion:** supply an API or internal integration token as `access_token`, or complete their OAuth flow in the web app. * **Generic MCP servers that use OAuth:** connect them through the web app's OAuth flow. Your personal Cleric key authenticates you to your instance; provider credentials authenticate Cleric to the integration. Connections you create are attributed to your Cleric user. ## Example Usage Once configured, you can ask your AI coding tool questions like: ``` What did Cleric find about the payment API latency spike? Which open issues does Cleric have a fix for in this repository? Did any of my changes from this week cause problems? What does the checkout service depend on? How many people used Cleric last week, and how did they rate it? ``` The AI tool calls the appropriate Cleric MCP tools to retrieve the data and include it in its response. # How Cleric Learns How Cleric improves over time Cleric continuously improves its understanding of your environment through several mechanisms. ## Calibration Cleric begins calibrating to your environment as soon as you connect your first integration. It analyzes the data sources to distill working knowledge it can draw on during investigations. Calibration tasks fall into two groups: * **Onboarding tasks**: Run during initial setup with the Cleric team and do not refresh on a schedule. * **Discovery tasks**: Run against your live infrastructure to build the service catalog and observability conventions. The service catalog discovery task re-runs automatically once a day so the catalog reflects your current infrastructure. You can review what Cleric has analyzed on the **System Health** page in the sidebar. ## Passive Context Collection Cleric automatically gathers context from: * **Alert structure**: Field names, severity indicators, alert groups * **Linked resources**: Dashboard URLs, runbook links in alert definitions * **Naming patterns**: Service naming conventions, metric patterns * **Infrastructure relationships**: Service dependencies, pod ownership The more issues Cleric investigates, the better it understands these patterns. ## Memories When you share facts about your environment during investigations, Cleric offers to remember them. [Memories](/learning/memories) capture factual knowledge like service dependencies, environment configurations, and known alert patterns. Memories are automatically recalled during future investigations when relevant. ## Topics Cleric maintains a written overview of your environment, organized into areas like alerts, architecture, observability, and deploys. Each Topic is a summary you can read to see what Cleric knows about that part of your system, and every claim links to the source it came from so you can verify it. This gives your team a standing reference instead of re-deriving how things work under pressure: which alerts are noise, where a service's logs live, how a release reaches production. Cleric writes each summary from the facts and memories it has gathered and checks them against live data sources, so the overview reflects your actual environment rather than out-of-date documentation. Because Cleric refreshes its topic summaries in the background, a topic can lag recent changes, and one that Cleric has gathered little about may be sparse or empty. Browse topics under **Knowledge > Topics** in the sidebar. ## Feedback Your interactions with Cleric provide valuable learning signals. Cleric learns from three types of feedback: * **Explicit Feedback:** Direct input you provide about Cleric's performance, including message ratings and corrections you share during conversations. * **Implicit Feedback:** Actions taken during and after investigations. When you follow Cleric's recommendations, ask follow-up questions, or pivot to a different area, these actions help Cleric understand what approaches are effective. * **Conversation Analysis:** Cleric analyzes past investigations to identify patterns. How your team discusses results, which areas require clarification, and how issues ultimately get resolved all inform future investigations. ### Message Ratings Rate any Cleric message on a 1-5 scale. This helps Cleric understand which responses were valuable and which missed the mark. **Rate liberally, especially low ratings.** When a response misses the mark, that feedback helps identify where investigations go wrong. Patterns in low ratings drive improvements to how Cleric approaches similar situations. If Cleric missed something or took the wrong approach, tell it directly in the conversation. Cleric learns from corrections and can adjust its investigation in real time. # Memories How Cleric remembers facts about your environment Memories are facts that Cleric learns from your conversations and uses to improve future investigations. They cover everything from system architecture and alert behavior to how you want Cleric to respond. ## How Memories Work When you interact with Cleric during an investigation, it identifies useful facts from your interactions and offers to remember them. These memories are then used in future investigations to provide more accurate and contextual analysis. ### Categories Cleric classifies each memory into one of these categories: * **Alerts & Runbooks**: triage rules, known false positives, escalation policy, and incident remediation playbooks * **Architecture & Data**: service dependencies, ownership, deployment topology, data stores, and data flows * **Observability**: where and how to query data, including dashboards, log and metric sources, queries, and metric names * **Infrastructure**: the platform layer beneath services: cloud accounts, Kubernetes, networking, and capacity * **Auth & Security**: authentication, authorization, secrets management, and security posture * **Integrations**: third-party vendors, external APIs, and the failure modes they introduce * **Deploy & Release**: CI/CD pipelines, rollout patterns, and release mechanics * **Developer Workflow**: source repositories, code and config locations, team ownership, and development conventions * **Domain & Product**: terminology, acronyms, business rules, and customer or company specifics * **Agent Behavior**: how Cleric should respond, including language, format, scope, and output conventions Cleric organizes the broader knowledge it gathers into these same categories. See [How Cleric Learns](/learning/how-cleric-learns#topics). ## Memory Proposals After you send a follow-up message during an investigation, Cleric may propose a memory based on what you shared. ### Example: Accepting a Memory During an investigation, you might share context: {% code overflow="wrap" %} ``` @Cleric The checkout service depends on inventory-api and pricing-api for real-time stock and price validation. If checkout is slow, always check those two services first. ``` {% endcode %} Cleric will propose a memory: {% code overflow="wrap" %} ``` Would you like me to remember this? "The checkout service depends on inventory-api and pricing-api for stock and price validation. When investigating checkout performance issues, check these dependencies first." [Remember] [Reject] ``` {% endcode %} Click **Remember** to save the fact. Cleric confirms: {% code overflow="wrap" %} ``` 👍 Memory saved. ``` {% endcode %} ### Example: Rejecting a Memory Sometimes Cleric might propose a memory that's not quite accurate: {% code overflow="wrap" %} ``` Would you like me to remember this? "High memory usage in the recommendation-engine always indicates a problem" [Remember] [Reject] ``` {% endcode %} If this isn't accurate (maybe high memory usage is normal during certain operations), click **Reject**: {% code overflow="wrap" %} ``` 👍 Memory rejected. ``` {% endcode %} You can then provide the correct context: {% code overflow="wrap" %} ``` @Cleric Actually, the recommendation-engine uses 6-8GB during cache warming between 5-7am daily. This is expected behavior, not a problem. ``` {% endcode %} Cleric will propose a corrected memory based on your clarification. ## Saving and Deleting Memories Directly In addition to memory proposals, you can directly tell Cleric what to remember or forget during any conversation. ### Saving a Memory {% code overflow="wrap" %} ``` @Cleric Remember that the checkout service depends on inventory-api and pricing-api ``` {% endcode %} Cleric saves the fact immediately and confirms. This is useful when you want to teach Cleric something without waiting for it to propose a memory. ### Deleting a Memory {% code overflow="wrap" %} ``` @Cleric Forget what you know about the staging database being shared with dev ``` {% endcode %} Cleric finds the matching memory and removes it. Use this to correct outdated information or remove facts that no longer apply. ## Managing Memories from the Web App Open **Knowledge > Memories** in the sidebar to browse, search, and filter every memory Cleric has stored. Click **Add memory** to save a fact directly, or hover a row and click the trash icon to delete one. These are the same operations as `@Cleric Remember…` and `@Cleric Forget…` in Slack. ## How Memories Are Used During investigations, Cleric automatically searches its memory for relevant facts based on the services, environments, and topics involved. For example, if Cleric is investigating an issue with the checkout service, it will search for any memories related to: * The checkout service specifically * Services that checkout depends on * The environment where the issue occurred * Similar alert patterns This helps Cleric: * Identify dependencies that aren't visible in monitoring data * Apply your preferred investigation approaches * Avoid paths you've indicated aren't useful * Recognize known patterns and false positives ## Querying Memories You can ask Cleric what it remembers about specific services, environments, or topics. ### Example: Service-Specific Memories {% code overflow="wrap" %} ``` @Cleric What do you remember about the checkout service? ``` {% endcode %} **Cleric's response:** {% code overflow="wrap" %} ``` **Dependencies:** • inventory-api, pricing-api (stock/price validation) • payment-gateway (transaction processing) • Check dependencies first when investigating performance **Known Behaviors:** • Connection pool: 25-30 connections during high traffic (from Jan 15 incident) • Memory: 1.2-1.5GB typical, 2GB spikes during flash sales (normal) **Operational:** • Owner: payments team (#payments-oncall) • 99.9% SLO, deploy window: Tue/Thu 10am-2pm PST **Investigation:** • Check recent deployments first for performance issues • Check read replicas before primary for database issues ``` {% endcode %} ### Example: Environment-Specific Memories {% code overflow="wrap" %} ``` @Cleric What do you know about our staging environment? ``` {% endcode %} **Cleric's response:** {% code overflow="wrap" %} ``` **Naming:** • Services: *-staging suffix (checkout-service-staging) • Namespaces: staging, staging-eu **Differences from prod:** • Smaller instance types • Shares DB with dev (performance impact) • Cache disabled • External APIs use sandbox endpoints **Investigation:** • Error rates 10-15% expected (vs <1% prod) • Performance 2-3x slower than prod ``` {% endcode %} ## Memory Cleanup Cleric reviews its memories after investigations to keep them accurate and relevant. Memories are removed when they: * Haven't been relevant to recent investigations * Are contradicted by newer information you've provided * No longer apply due to infrastructure changes # Security & Data Privacy Data access, retention, and platform infrastructure Cleric uses **read-only access** to your infrastructure and observability tools, enforced by RBAC or the access scopes each system supports. Cleric does not make changes to customer infrastructure but may propose them. All remediation actions are performed by your team. Some integrations also use write permissions so that Cleric can propose changes for your team to review, for example opening a pull request through GitHub or filing a Jira issue. Each section of [Supported Integrations](/integrations/supported-integrations) lists the permissions that integration needs and what Cleric uses them for. Cleric is instructed not to merge pull requests or push to your default branch. See the [GitHub integration](/integrations/supported-integrations#github) for the branch protection rule that enforces this. You control what Cleric can access across Observability (logs, metrics), Infrastructure (Kubernetes, cloud providers), Code, and Documentation. Cleric is SOC 2 Type II certified. The report, as well as our policies, pentest reports, and security program details are available in our [Trust Center](https://trust.cleric.ai). Annual penetration tests are performed by external security firms; the most recent was completed Q3 2026. ## Data Access ### What Cleric Can Access Minimum access required for investigation: * **Logs & Metrics**: Infrastructure and application logs and time-series telemetry via observability APIs ([Datadog](/integrations/supported-integrations#datadog), [Prometheus](/integrations/supported-integrations#prometheus), etc.) * **Kubernetes Metadata**: Read-only commands (`get pod`, `describe pod`, `get events`) * **Alert Metadata**: Content from alerting systems ([PagerDuty](/integrations/supported-integrations#pagerduty), [Grafana](/integrations/supported-integrations#grafana)) * **Source Code**: Optional, can be scoped to single repository * **Documentation**: Optional, from [Atlassian](/integrations/supported-integrations#atlassian) or [GitHub](/integrations/supported-integrations#github) Avoid exposing unnecessary personal data to Cleric. If you find personal data in Cleric investigations, contact us via or your dedicated Slack Connect channel to filter or disable specific data sources. ### Data Storage and Retention Cleric stores investigation data: queries executed, reasoning traces, evidence extracts cited in findings, and responses delivered to your team. Raw data from your environment (e.g. logs, metrics, traces, code) is queried at runtime and not persisted. * **System logs**: 30 days * **Application logs**: 120 days (configurable per customer requirements) * **On-demand deletion**: Request in writing, processed within 2 business days with confirmation ### Self-Learning and Tenant Isolation Cleric distinguishes between product improvement and self-learning. Both improve Cleric's behavior, but they use different data flows and storage boundaries. #### Product Improvement Data Flow Cleric product improvements are built from execution telemetry. Tenant agent systems emit telemetry one way to a centralized profiler. Profiler output is analyzed to produce agent updates, and those updates are deployed back to each tenant. Tenant agent systems do not pull customer data, tenant memory, or investigation context from the profiler. ```mermaid %%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#F7F7F5', 'primaryBorderColor': '#D7D7D4', 'primaryTextColor': '#313131', 'lineColor': '#6B6B6B', 'clusterBkg': '#EBF0FA', 'clusterBorder': '#C2D0EB', 'fontFamily': 'Inter, Inter Fallback, system-ui, arial'}, 'flowchart': {'curve': 'basis', 'rankSpacing': 65, 'subGraphTitleMargin': {'top': 10, 'bottom': 10}}, 'themeCSS': '.nodeLabel, .nodeLabel p, .edgeLabel .labelBkg, .edgeLabel .labelBkg p { font-family: Inter, Inter Fallback, system-ui, arial !important; } .edgeLabel .labelBkg, .edgeLabel .labelBkg p { background-color: #D8DFEF !important; } .edgeLabel .labelBkg, .edgeLabel .labelBkg span, .edgeLabel .labelBkg p { color: #6B6B6B !important; font-size: 13px !important; }'}}%% flowchart LR subgraph Tenants["Tenant agent systems"] A("Tenant A") B("Tenant B") C("Tenant C") end P("Centralized profiler") R("Agent updates") A -. "One-way telemetry" .-> P B -. "One-way telemetry" .-> P C -. "One-way telemetry" .-> P P --> R R --> A R --> B R --> C classDef tenant fill:#FFFFFF,stroke:#D7D7D4,color:#313131 class A,B,C tenant style Tenants color:#3967C8,rx:8px,ry:8px ``` #### Self-Learning Data Flow Self-learning happens inside each tenant. Within the tenant boundary, the Agent System writes and reads operational Memory, including infrastructure context, prior investigation outcomes, team playbooks, and engineer corrections. That Memory is scoped to the dedicated customer instance and database. Customer A's Memory is not copied into Customer B's tenant, and tenant Memory is not promoted into a shared model. ```mermaid %%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#F7F7F5', 'primaryBorderColor': '#D7D7D4', 'primaryTextColor': '#313131', 'lineColor': '#6B6B6B', 'clusterBkg': '#EBF0FA', 'clusterBorder': '#C2D0EB', 'fontFamily': 'Inter, Inter Fallback, system-ui, arial'}, 'flowchart': {'curve': 'basis', 'rankSpacing': 75, 'nodeSpacing': 53, 'subGraphTitleMargin': {'top': 10, 'bottom': 10}}, 'themeCSS': '.nodeLabel, .nodeLabel p, .edgeLabel .labelBkg, .edgeLabel .labelBkg p { font-family: Inter, Inter Fallback, system-ui, arial !important; } .edgeLabel .labelBkg, .edgeLabel .labelBkg p { background-color: #F8F8F8 !important; } .edgeLabel .labelBkg, .edgeLabel .labelBkg span, .edgeLabel .labelBkg p { color: #6B6B6B !important; font-size: 13px !important; } .edgeLabel { translate: 0 -14px; }'}}%% flowchart LR subgraph TenantA["Tenant A"] AgentA("Agent System") MemA("Memory") AgentA --> MemA MemA --> AgentA end subgraph TenantB["Tenant B"] AgentB("Agent System") MemB("Memory") AgentB --> MemB MemB --> AgentB end subgraph TenantC["Tenant C"] AgentC("Agent System") MemC("Memory") AgentC --> MemC MemC --> AgentC end TenantA <-. "No access" .-> TenantB TenantB <-. "No access" .-> TenantC classDef tenant fill:#FFFFFF,stroke:#D7D7D4,color:#313131 class AgentA,MemA,AgentB,MemB,AgentC,MemC tenant style TenantA color:#3967C8,rx:8px,ry:8px style TenantB color:#3967C8,rx:8px,ry:8px style TenantC color:#3967C8,rx:8px,ry:8px ``` Cleric may use the tenant's operational memory as context for future investigations in that same tenant but has no access to other tenant memory. ## Model & Inference Privacy ### No Model-Training Risk * Your data is **never** used to train or fine-tune models * Enterprise LLM APIs include contractual zero-data-training and zero-data-retention guarantees * All AI agent actions are logged and auditable ### Where Models Run * LLM providers: Anthropic, Google Gemini, and OpenAI * Model calls route from your isolated Cleric instance to provider enterprise API endpoints ## Platform Security Cleric is a **single-tenant SaaS solution** with complete isolation between customers. ### Architecture & Isolation * **Dedicated Infrastructure** * Isolated compute with network boundaries per customer * Dedicated instance (frontend and backend) * Dedicated PostgreSQL database per customer (not publicly accessible) * Customer-specific domain (`.app.cleric.ai`) * Data encrypted at rest using AES-256 * **Hosting** * GCP `us-east4` by default, alternative regions on request * EU-hosted instances run the application, database, and model inference in Europe, with observability and analytics processed centrally in the US. See [EU Hosting & Data Processing](/security/eu-hosting-data-processing) * **Infrastructure as Code** * 100% Terraform-managed infrastructure * All changes subject to automated CI/CD checks and security scans * No direct production server access via SSH or similar protocols ### Network Security & Egress * **Encryption in Transit** * TLS 1.2 or higher for all external connections * Internal service-to-service communication encrypted * Managed certificates * **Static Egress IP** * Dedicated static egress IP per instance for allowlisting * **Compromise Detection** * Monitors infrastructure for suspicious activity (privilege escalation, secret changes, IaC bypasses) * Centralized alerts reviewed by security on-call ### Internal Access Controls * Only Engineering team members have production access * Multi-factor authentication (MFA) required for all production systems * User access reviews performed at least annually ### Availability & Recovery * **Backups**: Automated daily backups with point-in-time recovery. Seven daily backups retained, encrypted, and stored in multi-region location. * **High availability**: Multi-zone GKE clusters. Cloud SQL PostgreSQL with 99.95% availability SLA ### Security Monitoring & Incident Response * **Automated Security Scanning** * Semgrep for static code analysis * Grype for dependency and container image vulnerability scanning * Checkov for infrastructure-as-code misconfiguration detection * gitleaks for secret detection * GitHub Dependabot for dependency vulnerabilities * Oneleet for cloud security monitoring * Vulnerability remediation SLA: High/Critical within 7 days * **Incident Response** * Security incidents escalated to * Customer notification within 24 hours for critical incidents affecting customer data * Post-incident review within 5 business days for medium to critical incidents ## Contact * **General inquiries**: * **Security incidents**: # EU Hosting & Data Processing Where each category of data is processed for EU-hosted instances EU-hosted instances run the application, database, and model inference in Europe. Operational logs, traces, error analysis, and product analytics are processed centrally in the US. EU hosting is not an EU-only data boundary. | Data category | Used for | Location | | ----------------- | -------------------------------------------- | --------------------- | | Application | Running your dedicated instance | EU (`europe-west1`) | | Database | Storing investigation data and tenant Memory | EU (`europe-west1`) | | Model inference | Real-time investigation reasoning | EU regional endpoints | | Operational logs | Operating and supporting the service | US | | Traces | Debugging and improving agent behavior | US | | Error analysis | Detecting and fixing application errors | US | | Product analytics | Measuring product usage | US | ## What Runs in the EU * **Application**: The dedicated instance (frontend and backend) runs on GCP in `europe-west1` (Belgium). * **Database**: The dedicated application database, which stores investigation data and tenant [Memory](/learning/memories), runs in `europe-west1`. * **Model inference**: Real-time model calls route from the instance to model provider endpoints in EU regions. Data queried from your environment during an investigation (logs, metrics, code, documentation) is processed in the EU at runtime. Cleric does not store this raw data. It persists extracts of the evidence for citations, suggestions, and recommendations: a query over ten minutes of logs stores only the suspicious error lines. These extracts are stored in the application database in `europe-west1`. See [Data Storage and Retention](/security/security-data-privacy#data-storage-and-retention). ## What Is Processed in the US Cleric operates observability and analytics from a central US control plane for all instances, including EU-hosted ones. * **Operational logs**: Application and system logs export to Cleric's central US environment. The Cleric team uses them to operate and support the service. Log entries can include investigation context such as queries executed and error output. Retention follows [Data Storage and Retention](/security/security-data-privacy#data-storage-and-retention). * **Traces**: Agent execution traces, including model inputs and outputs, are recorded in the US. Cleric engineers use them to debug and improve agent behavior. Your data is never used to train or fine-tune models. See [No Model-Training Risk](/security/security-data-privacy#no-model-training-risk). * **Error analysis**: Application errors report to centralized error monitoring in the US. * **Product analytics**: Usage analytics from the Cleric web application are processed in the US. The one-way execution telemetry described in [Product Improvement Data Flow](/security/security-data-privacy#product-improvement-data-flow) is also processed in the US. {% hint style="info" %} If these US data flows conflict with your compliance requirements, contact or your dedicated Slack Connect channel. {% endhint %} # FAQ Frequently Asked Questions Quick answers to common questions. See linked docs for details. ## General
What is Cleric? Cleric is an AI SRE that investigates production issues by querying your observability tools and infrastructure. See [Overview](/).
What platforms does Cleric integrate with? Kubernetes, AWS, GCP, Datadog, Grafana, Prometheus, PagerDuty, GitHub, Confluence, Elasticsearch, and more. New integrations are added regularly based on customer needs. See [Integrations](/integrations/supported-integrations).
## Using Cleric
How do I interact with Cleric? Web UI and Slack. See [Collaborating with Cleric](/usage/collaborating-with-cleric).
How do I start an investigation? Three ways: (1) **Automatic**: Configure keyword-based alert monitoring in Slack channels so Cleric investigates matching alerts automatically. (2) **On-demand in Slack**: Mention `@Cleric` in any channel or thread with a question or issue description. (3) **On-demand in the web UI**: Click "New issue" and describe the problem. You can also ask Cleric proactive questions outside of any alert, such as "run a health check on the payments service." See [Collaborating with Cleric](/usage/collaborating-with-cleric).
What does !investigate do? Adding `!investigate` to your message (in Slack or the web UI) triggers a full deep investigation instead of the default conversational mode. This gives you the same thorough analysis that alert-triggered investigations receive. Works when starting a new investigation or on follow-up messages in an existing thread. See [Deep Investigations](/usage/collaborating-with-cleric#deep-investigations-with-investigate).
How does Cleric connect to my cloud infrastructure (AWS, GCP, etc.)? You provide Cleric with scoped credentials for each system. For AWS, you create an IAM role with a trust policy that grants Cleric access to specific services (e.g., CloudWatch, EKS). For Kubernetes, you create a service account with RBAC permissions. For SaaS tools (Datadog, PagerDuty, etc.), you provide an API key. Cleric provides draft policies and configurations that you can edit to match your security requirements. You control exactly what Cleric can and cannot access. See [Integrations Overview](/integrations/overview).
Does Cleric handle the full incident lifecycle? Yes: from alert to root cause to recommended fix to summary report. See [How Investigations Work](/usage/how-investigations-work).
Can Cleric take actions or just investigate? Cleric primarily investigates using read-only access. The GitHub integration includes write permissions by default, allowing Cleric to create branches, open pull requests, and file issues. Cleric is instructed that it cannot merge PRs directly. We recommend configuring branch protection rules on your default branch. See [GitHub integration](/integrations/supported-integrations#github) for details. If you grant the Atlassian user "Create Issues" permission, Cleric can also create Jira tickets from investigation findings. See [Atlassian integration](/integrations/supported-integrations#atlassian) for details.
Does Cleric replace my monitoring dashboards? No. Cleric works alongside your existing observability tools (Datadog, Grafana, etc.), not instead of them. See [Supported Integrations](/integrations/supported-integrations).
Can Cleric connect findings across different tools? Yes. Cleric correlates data across all connected integrations (logs, metrics, deployments, code changes, and more). See [Supported Integrations](/integrations/supported-integrations).
Can Cleric use our internal documentation? Yes. Cleric searches Confluence, GitHub docs, and other sources during investigations, respecting your existing access controls. See [Providing Context](/setup/providing-context).
How do we decide what to configure Cleric to respond to? Start with high-frequency or high-complexity alerts. See [Configuring Automations](/setup/agents-and-triggers).
What's the difference between agents and triggers? An **agent** is a named workflow with instructions (e.g., `investigate`, or your own `checkout-5xx`). A **trigger** is a rule that runs an agent automatically when a matching event fires. Cleric supports two trigger types: **Bot message** (fires when a bot message posted in a Slack channel matches the trigger's keywords) and **Scheduled** (fires on a recurring schedule). You can also run an agent on-demand with `!agent-name` even if no trigger exists for it. See [Configuring Automations](/setup/agents-and-triggers).
How can we provide feedback on Cleric's responses? In the web app or Slack thread. See [How Cleric Learns](/learning/how-cleric-learns).
What access does Cleric need to our infrastructure? Cleric investigates with read-only access to your tools. Some integrations also use write permissions, limited to proposing changes for review, such as opening a pull request or filing an issue. See [Connecting Integrations](/integrations/supported-integrations) for the permissions each integration needs.
What happens if Cleric encounters an error during investigation? Cleric continues with available sources and notes failures in the Activity Log. See [Reviewing the Activity Log](/usage/reviewing-the-activity-log).
What happens when Cleric needs more information during an investigation? For user-initiated investigations, Cleric asks clarifying questions in the same Slack thread or web chat and waits for your response before continuing. For alert-triggered investigations, Cleric completes with available data and reports any gaps or access limitations in its findings. See [How Investigations Work](/usage/how-investigations-work#when-cleric-needs-more-information).
Why did Cleric attach a new alert to an existing issue instead of starting a new investigation? When a new alert in a Slack channel looks like the same problem as a recent issue in that channel, Cleric attaches it to the existing issue instead of creating a new one. This keeps related alerts together and avoids parallel investigations for the same incident. See [How Investigations Work](/usage/how-investigations-work#from-alerts).
How does Cleric learn about our environment? Cleric scans connected integrations and learns from each investigation. See [How Cleric Learns](/learning/how-cleric-learns).
Can Cleric handle incidents that span multiple systems? Yes. Cleric automatically maps service dependencies and traces issues across system boundaries. See [How Cleric Works](/meet-cleric/how-cleric-works).
Should we deploy Cleric in non-production environments? Focus on production. Dev/QA environments have less structured data. See [Quick Start](/meet-cleric/quick-start).
How do I get help with an issue not covered here? Contact or reach out via your dedicated Slack Connect channel with the Cleric team. Available Monday-Friday, 9am-6pm PT.
## Security & Privacy
Is there an audit trail of what Cleric does? Yes. Every investigation logs what Cleric accessed and the steps it took. See [Reviewing the Activity Log](/usage/reviewing-the-activity-log).
Does Cleric have SOC2 certification? Yes. Cleric is SOC 2 Type II certified. Our report is available in our [Trust Center](https://trust.cleric.ai).
Exactly what data does Cleric ingest and store? Investigation data (queries executed, reasoning traces, and responses). Your logs, metrics, and code are queried at runtime and not persisted. See [Security & Data Privacy](/security/security-data-privacy).
Does Cleric use my data to train AI models? No. Your data is never used to train or fine-tune models. See [Security & Data Privacy](/security/security-data-privacy).
Can I request deletion of my data? Yes. Request deletion anytime. See [Data Storage and Retention](/security/security-data-privacy#data-storage-and-retention).
Can I request deletion of a specific investigation? Yes. If an investigation report contains data you want removed, contact us via or your dedicated Slack Connect channel. Specific investigations can be deleted on request. See [Data Storage and Retention](/security/security-data-privacy#data-storage-and-retention).
Does Cleric deploy anything in my infrastructure? No. Cleric runs entirely in a dedicated, single-tenant cloud environment (`.app.cleric.ai`). No agents, sidecars, or daemons run in your clusters or cloud accounts. Cleric connects to your systems using the credentials you provide (API keys, IAM roles, service accounts) and queries them remotely. The only exception is the optional [Connector](/integrations/private-resources) for accessing private resources (e.g., a Kubernetes cluster without a public API endpoint), which you deploy and control.
Is Cleric available for self-hosting? No. Cleric is SaaS-only.
Does Cleric support Single Sign-On (SSO)? Yes, via WorkOS (compatible with all major SSO providers). See [Setting up SSO](/setup/setting-up-sso).
# Changelog Recent updates to Cleric Every month, we update this changelog with the major features and bug fixes that were shipped to our customer environments. ## September 2026 September focused on how you work with Cleric day to day. Chats, changes, and issues each have a dedicated page in the web app, and Cleric now joins incident channels as they are created and can start investigating from the first messages. **New Features** * **Changes**: Added a **Changes** tab that lists the changes Cleric tracked as a dated log. Each change has a page showing its author, release, the services it could affect, and every expectation Cleric set with how it was checked. When a change violates an expectation after rollout, Cleric opens an issue, notifies the change's author, and tracks it to resolution. See [Change Verification](/usage/change-verification). * **Issues**: Rebuilt the Issues page as a work queue, so you can review all of your environment's problems in a single pane. It opens on what is still open, orders by last activity, and groups by status, affected service, source, or resolved reason. * **Chats**: Added a **Chats** tab for conversations with Cleric that don't require a deep investigation. General queries start as chats. Ask Cleric to `investigate` to promote a chat to an issue. * **Better incident support**: Added the ability to configure Cleric to join an incident channel and start investigating immediately as soon as the incident is created. Cleric can use the context of all conversation threads in the incident channel when responding to queries. See [Incident Channels](/usage/collaborating-with-cleric#incident-channels). * **New integrations**: * **ClickHouse**: Added read-only access to failing and slow queries, stuck merges and mutations, replication, memory, and disk, plus query logs and events you store there. * **incident.io**: Added incidents, updates, alerts, follow-ups, and service ownership to investigations. When you ask, Cleric can post an update, create a follow-up, or import a post-incident document. * **Honeycomb queries**: Added running queries against your Honeycomb environments, including a trigger's own query. **Also Shipped** * **Improved grouping of repeat alerts**: An alert that matches an open issue created in the prior 24 hours now joins that issue, avoiding a separate investigation for each repeat alert. * **Send Cleric responses to Slack**: When an issue has a connected Slack thread, you can now send Cleric's response to that thread with **Post to Slack thread**. * **Typeahead references in web chat**: Type `@` in a chat input to reference Linear issues and GitHub pull requests directly. * **Tag your teammates from web:** Tag a teammate with an `@mention` from any chat input. Cleric will send them a Slack DM to let them know. * **Dark mode!** Toggle your appearance settings in **Settings > Personal**. **Bug Fixes** * **Recurring issues**: Fixed Cleric leaving an issue resolved when it recurred. Cleric's resolution monitor now reassesses against every occurrence on the issue and its merged duplicates. * **Unmerging issues**: Fixed a bug where Cleric would re-group an issue you had previously un-grouped, preventing you from accessing the conversation history. * **Slack mentions**: Fixed a bug where Cleric would ignore a message that was edited to include an at-mention. * **Container Memory**: Fixed memory readings that counted a restarted container's retained instance alongside the live one. When instances overlap, Cleric withholds the total and says why. * **Metric and Log Timelines**: Fixed a dip that recovered inside a downsampled bucket never reaching Cleric. Each bucket now carries its minimum and average as well as its maximum. * **Miscellaneous fixes**: Fixed keyword triggers missing a bolded keyword, connection tests for MCP, BuildKite, Bitbucket, and Honeycomb, and double Slack formatting in chat messages. ## August 2026 In August, Cleric made it easier to focus on the issues that need action, address feedback and CI failures on the pull requests it creates, and manage the connections and usage that support your workspace. **New Features** * **Duplicate Issue Merging**: Keep recurring alerts with the investigation that already explains them. When a new alert has the same underlying cause as an earlier issue, Cleric adds its evidence to that issue and takes you there. * **Alert Noise Reduction Stats**: See how much alert noise Cleric kept from becoming work for your team. The Performance page now shows the share of alerts that did not require action and how that changed from the previous period, including alerts that were grouped before investigation, merged afterward, or verified as resolved or false positives. * **Pull Request Follow-through**: When a Cleric-created pull request receives reviewer comments or a CI failure, Cleric addresses the feedback or failure and posts updates in the linked thread. * **Rebuilt Integrations Page**: Find, set up, and maintain integrations from one clearer place. **Installed** shows your connected integrations, surfaces connections that need attention, and displays a connection count; **Catalog** makes every available integration searchable by category. Each integration now has its own page for connections and setup. * **Usage**: Track credit consumption against your billing-period allowance in the new Settings > Usage tab. It also flags overages and lets you review earlier periods. * **Recommendations on System Health**: Prioritize the setup work that will make Cleric more effective in your environment. Choose which Slack channel receives recommendations, then review and dismiss them from the System Health page. * **Improved Issue Search and Filtering**: Find past issues using details from anywhere in a conversation, then filter the list by participant. * **New integrations**: * **Honeycomb**: Let Cleric use your Honeycomb trigger definitions to understand the condition an alert watches, how it is evaluated, and who it pages. * **Bitbucket Cloud**: Bring Bitbucket Cloud code, commits, pull requests, and Pipelines into investigations, and let Cleric open a pull request for review. * **Slite**: Make runbooks, incident procedures, and other documentation in Slite available to investigations with read-only access. * **Grafana SQL datasources**: Query MySQL, PostgreSQL, and other SQL datasources through Grafana alongside the metric datasources Cleric already supports. **Bug Fixes** * **Resolution and Check Updates**: Fixed Cleric posting resolution and scheduled-check updates when there was nothing new to report. * **Sign-out**: Fixed sign-out leaving a session valid when the browser did not follow the logout redirect. Sessions are now revoked server-side. * **Integration Credentials**: Fixed follow-ups using stale credentials. Cleric reloads an integration connection after its credentials are updated. * **Change Verification Attribution**: Fixed verification updates crediting a bot for a change or omitting people responsible for it. * **Slack Mentions**: Fixed mentions on Markdown header lines rendering as literal text and failing to notify the intended person. * **Scheduled Checks**: Fixed checks reporting their initial state regardless of what happened, which delayed a verdict until expiration. Failed probes, unreadable output, and empty results now report as inconclusive. * **MongoDB Atlas**: Fixed invalid metric queries and added access to disk and database endpoints. ## July 2026 July added Change Verification, scheduled checks for every agent, and narrow-screen layouts in the web app. **New Features** * **Change Verification**: Added a built-in `verify` agent that checks a released change against production evidence. It determines whether the intended outcome occurred, whether anything regressed, and which checks need a longer observation window. Run it on demand with `!verify` followed by a pull request link or change description, or set up a trigger to run it automatically for every deployment notification in a release channel. See [Change Verification](/usage/change-verification) for more. * **Scheduled checks for any Agent**: The `investigate` agent and custom agents can now use scheduled checks. All agents have the capability to rerun a command on a cadence until the reported state changes or a time limit expires. * **Updated Slack channel context**: Added tools that let Cleric read messages around an alert and list accessible channels, to improve context gathering in the initial investigation. **Bug Fixes** * **Service Map**: Fixed service-list links opening the full map when the selected service had no dependencies. Reset also clears the focused service and its URL parameter. * **Issue Filters**: Fixed the agent filter listing agents that do not apply to the selected view. * **Slack Commands**: Fixed a single `!agent` command producing an error when the message also contained a link with display text. * **Slack Mentions**: Fixed mention tokens appearing inside code formatting, which prevented Slack from notifying the referenced person. * **GitHub Credentials**: Fixed expired GitHub credentials interrupting long-running agent sessions. Cleric refreshes tokens before the expiration time reported by the GitHub API. * **Metric Aggregation**: Fixed per-entity metrics, such as per-pod gauges, being summed and reported as a single fleet-wide value. Cleric now selects aggregation based on what the metric measures and treats partially ingested trailing data points as incomplete. * **Improved Integration Reliability**: Fixed common tool error patterns in the Linear, Sentry, Grafana, Loki, and Prometheus integrations. ## June 2026 **New Features** * **Live Hypotheses**: While an investigation runs, Cleric now shows the hypotheses it is actively testing, in both Slack and the web app, so you can see where it is headed before it reaches a conclusion. In Slack the hypotheses update in place and link back to the full view in the web app. * **Proactive Resolution Updates**: When Cleric verifies that an issue has resolved, it posts an update to the Slack thread and adds a ✅ reaction to the root message. If the issue reopens, Cleric removes the reaction. * **Service Dependency Map**: The Services page has a new Map tab that shows how your services depend on one another, built from Cleric's service catalog. Search for a service to focus the map on it and its request flow. * **Investigations View**: The Issues page now opens on a new Investigations tab, which lists Cleric's deep investigations grouped by status: Investigating, Inconclusive, Fix suggested, Monitoring, and Resolved. Switch to the All issues tab for every issue, including those handled by custom agents. * **Search Knowledge from your IDE**: The Cleric MCP server adds a `search_knowledge` tool. Your coding agent can now query Cleric's knowledge base: saved memories and extracted facts. See [MCP Server](/integrations/mcp). * **New integrations**: * **Amplitude**: Give Cleric read-only access to event volumes, active and new user counts, segmentation, saved charts, and annotations. Cleric can compare these against an investigation's time window. * **Unleash**: Give Cleric read-only access to feature flags, their per-environment state, activation strategies, and change history, so it can check whether a flag changed around the time an alert fired. Self-hosted instances are supported. **Bug Fixes** * **Activity Log Timing**: Fixed per-tool durations in the activity log so each tool call reflects the time it actually took. * **Datadog Connection Test**: Fixed the Datadog connection test to validate the application key in addition to the API key. Misconfigured keys now fail at setup. * **Atlassian Connection Test**: Fixed the Atlassian connection test to validate the API token before saving the integration. ## May 2026 **New Features** * **Define your own Cleric workflows with Automations**: Until now Cleric ran one built-in investigation on every alert. You can now define multiple named agents, each with its own instructions, and control when each one runs with triggers. Route matching alerts to an agent with channel-scoped keyword triggers, run agents on a recurring schedule, or run any agent on demand with `!agent-name`. * **See and manage what Cleric knows with Knowledge**: Everything Cleric has learned or been taught about your environment now lives in one place in the web app. This brings together memories, facts Cleric picks up about your environment as it works, and the procedures (formerly "Skills") you have taught it. * **Topics**: A new background agent indexes your connected data sources and saves durable, human-authored facts (service ownership, runbook pointers, recurring failure patterns) into a queryable knowledge base, reducing the effort you have to spend teaching Cleric directly. * **Memories**: A new Knowledge > Memories page lets you search, add, and delete memories. Memories now carry an author, a created date, and a relevance score, so you can see what context has the highest impact on Cleric's responses. * **Monitor Cleric's calibration status via System Health**: A new System Health page shows the status of Cleric's onboarding and discovery tasks, so you can see how it is learning your environment. * **New Slack tools**: * **Slack Mentions**: Cleric can now @-mention Slack users in its replies. You can instruct Cleric to identify a service owner, the on-call engineer, or the committer of a change, and Cleric will map that person to the right Slack user and notify them. * **Post to Slack from web**: While continuing an investigation in the web UI, you can ask Cleric to post its reply in the connected Slack thread. * **New integrations**: * **Cloudflare**: Allow Cleric read-only access to DNS, WAF events, Workers, traffic analytics, load balancers, SSL/TLS, and audit logs. * **Linear**: Cleric can now create and reference Linear issues during investigations. * **Notion**: Connect Notion and Cleric can search Notion pages and databases during investigations. * **Buildkite**: Cleric can now query Buildkite pipelines, builds, jobs, and annotations. **Bug Fixes** * **Slack URL Formatting**: Fixed bold emphasis being applied around bare URLs in Slack replies. * **Budget Messaging**: Fixed the over-budget message to show a friendly reset duration instead of raw values. * **Cloudflare Token Validation**: Fixed Cloudflare connection tests to use account-scoped endpoints so tokens with account-level permissions validate correctly. ## April 2026 This month focused on getting Cleric's findings into the tools you already use, and on cutting alert noise as coverage grows. **New Features** * **Alert Grouping**: Repeat alerts no longer fan out into separate issues. When a new alert in a Slack channel matches a recent issue there, Cleric attaches it to that issue instead of opening a new one. The number of grouped alerts appears in the issues list, along with the affected services. * **Background Discovery**: Between investigations, Cleric studies your logs and metrics query conventions and applies them during investigations, so it reaches results faster and makes fewer query syntax errors. * **MCP Server**: Access your Cleric investigation data from your IDE. Connect Claude Code, Cursor, or any MCP client with a personal API key, then search, list, and create issues and pull root cause and evidence into your coding agent. Generate a key under Settings, on the Personal tab. See [MCP Server](/integrations/mcp). * **Citations in Slack**: When the cited sources are available, Cleric now links to them in its Slack responses, the same as in the web app. * **Issue Slugs**: Every issue now carries a short, human-readable ID like `ISS-3912`, so you can reference a specific investigation in chat or a ticket. * **New Relic Integration**: Cleric can now query New Relic logs, metrics, traces, alerts, and entities during investigations, through NerdGraph and NRQL. * **Sentry Integration**: With Sentry connected, Cleric can inspect issues, events, stack traces, releases, and project-level error patterns during investigations. **Bug Fixes** * **Memory Proposals**: Fixed memory proposals being truncated in the UI, so you can read the full proposal before accepting it. * **Web Follow-ups**: Fixed web follow-up messages timing out. Cleric processes them in the background now instead of returning a 504. * **Login Errors**: When sign-in fails, the page now displays the reason instead of a raw error response. ## March 2026 **New Features** * **Contextual Responses**: Cleric now responds to thread replies without an explicit `@Cleric` mention when it's part of the conversation. Disable per thread with `@Cleric mute`. * **Scheduled Follow-ups**: Schedule the agent to check back on an issue at a specific time. Results post to your Slack thread automatically. See [Common Use Cases](https://github.com/ClericHQ/cleric-core/tree/main/docs/public/investigation/common-use-cases/README.md#monitoring-production) for examples. * **Stop Slack Command**: You can now type `@Cleric stop` to interrupt a running investigation from Slack. * **MongoDB Atlas Integration**: Cleric can now query your MongoDB Atlas databases during investigations. * **Splunk Integration**: Cleric can now search and analyze your Splunk logs during investigations. **Bug Fixes** * **Follow-up Quality**: Follow-up responses now require evidence-based reasoning before drawing conclusions, reducing unsupported answers. * **Agent Recovery**: Fixed a bug where agents interrupted mid-investigation could not resume follow-up interactions. ## February 2026 This month focused on investigation transparency and interactive follow-up. Citations moved to general availability with direct links to data sources, memory tools are enabled for all customers, and Slack investigations gained new interactive follow-up buttons. **New Features** * **Citations**: Added citation links to investigation results referencing the specific data sources consulted. * **Past Issues**: Added search over past investigations when analyzing new issues. Cleric references prior investigations to identify recurring patterns. * **Memory Tools**: Added explicit save and delete memory tools during investigations. You can now tell Cleric to "remember" and "forget". * **Dynamic Follow-up Prompts**: Added dynamic context-specific prompt suggestions to investigation responses in both web and Slack. * **Copy Investigation Summary**: Added a copy button to the issue view in the web, so you can easily transfer the investigation summary to your chosen coding agent. * **Integration Enable/Disable**: Added the ability to enable or disable individual toolkits without removing the integration configuration. * **Integration Health Status**: Added an integration health status indicator to the sidenav, making it more visible when an integration connection is unhealthy. ## January 2026 This month focused on extensibility and integration expansion, with custom skills for environment-specific workflows, Confluence integration for documentation search, and GitHub Enterprise support for self-hosted instances. **New Features** * **Custom Skills**: Added Skills management in the UI to teach Cleric environment-specific knowledge and workflows. Cleric suggests new Skills when it encounters unfamiliar tasks. * **Confluence Integration**: Added support for searching and analyzing Confluence documentation during investigations. * **GitHub Enterprise Support**: Added support for self-hosted GitHub Enterprise instances for code analysis in air-gapped or on-premise environments. * **AWS CloudWatch Skill**: Added CloudWatch metrics and logs analysis to diagnose infrastructure issues on AWS. * **Slack File Attachments**: Added support for attaching files to Slack messages when providing context for investigations. **Bug Fixes** * **Response Previews**: Fixed Slack notification previews to display the agent's response instead of generic placeholder text. * **Agent State Recovery**: Resolved issues with restoring investigation sessions that could prevent follow-up interactions from working correctly. ## December 2025 This month we focused on resilience and infrastructure expansion. We introduced automatic investigation recovery, expanded cloud infrastructure support with an EKS integration, and improved how alert responses are configured. **New Features** * **EKS Integration**: Added support for AWS EKS toolkit to investigate issues in your Kubernetes clusters running on Amazon EKS * **Alert Processing Rules**: Alert processing rules are now fully configurable with keywords, making it easier to manage which alerts Cleric responds to in Slack **Bug Fixes** * **Database Stability**: Resolved connection pool exhaustion issues that could cause service disruptions during high load * **Slack Feedback Submission**: Fixed errors that prevented feedback modal submissions from completing successfully ## November 2025 This month focused on expanding integration capabilities and improving investigation control. We introduced new cloud infrastructure integrations, enhanced the onboarding experience, and added the ability to interrupt investigations when needed. **New Features** * **AWS Integration**: Added support for AWS toolkit with role-based access to EC2, CloudWatch, EKS, and other AWS services for investigating infrastructure issues * **Cancel Investigation**: You can now pause an in-progress investigation when you no longer need Cleric to continue analyzing an issue * **Enhanced Onboarding**: New guided signup flow with a 4-step onboarding process makes it easier to get started with Cleric **Bug Fixes** * **Follow-up Reliability**: Resolved problems with subagent initialization that could prevent Cleric from responding properly to follow-up questions * **GitHub Integration Cleanup**: GitHub app is now properly uninstalled from the organization when removing the GitHub toolkit ## October 2025 This month focused on enhancing investigation interactivity and expanding regional support. We introduced a new activity log view for better visibility into investigation progress and enabled follow-up conversations to continue collaborating with Cleric after the initial investigation. **New Features** * **Activity Log View**: New interface on the Issue Details page provides a chronological view of all investigation steps, making it easier to understand Cleric's reasoning process and progress * **Follow-up Interactions**: You can now continue conversations with Cleric in Slack threads after the initial investigation completes, enabling iterative debugging and clarification * **EU Region Support**: Added AWS Bedrock support so model inference for EU-hosted instances runs on EU infrastructure. See [EU Hosting & Data Processing](/security/eu-hosting-data-processing) for where each category of data is processed * **Enhanced GitHub Integration**: Improved GitHub CLI integration enables more comprehensive code analysis during investigations **Bug Fixes** * **Slack Message Formatting**: Fixed errors that occurred when investigation responses exceeded Slack's message length limits by automatically truncating long messages * **Follow-up Processing**: Resolved issues where alert thread messages with mentions weren't being properly processed, ensuring Cleric responds reliably to all follow-up questions * **Investigation State Tracking**: Fixed a bug where follow-up interactions weren't correctly updating the investigation state, ensuring all conversation context is preserved ## September 2025 This month focused on enhancing collaboration workflows and improving investigation reliability. We introduced new ways to interact with Cleric directly in Slack and streamlined the integration setup process. **New Features** * **Slack Response Interaction**: You can now interact directly with Cleric's investigation responses in Slack, making it easier to collaborate and provide feedback without switching contexts * **GitHub App Integration**: New streamlined GitHub app installation flow simplifies connecting your repositories for code analysis during investigations * **All Observations Tab**: Added a dedicated tab to the Issue Details page to view all observations collected during an investigation in one place ## August 2025 With this update we shipped a handful of small security enhancements and experience improvements. Most updates were internal infrastructure, testing, or development workflow changes that don't affect customers directly. **New Features** * **Enhanced Investigation Display**: Streamlined the observations view with improved hypotheses and evidence presentation for clearer investigation results * **Elasticsearch Integration**: Added log search and analysis capabilities for customers with Elasticsearch deployments * **Enhanced Security**: Implemented HTTP security headers and refresh token support to strengthen authentication and session management **Bug Fixes** * **Investigation Error Visibility**: Error messages are now displayed in the UI when Cleric fails to investigate an issue, providing better transparency into investigation status * **Investigation Confidence**: Resolved over-confidence calculation issues to ensure investigation confidence scores accurately reflect the strength of evidence ## July 2025 July focused on strengthening security, rearchitecting Cleric's initial investigation result, and improving the onboarding experience. **New Features** * **Improved Issue Details View**: New Canvas layout that replaces Findings with Hypotheses and Observations. In the UI, you can view Cleric's hypotheses about the issue's potential root cause, and hover over citations to preview the referenced observations. * **Guided Onboarding Process**: New users now see a progress tracker that shows which integrations need setup and provides clear next steps to get fully configured * **Enhanced Data Isolation**: We added organization-level access controls as an additional layer on top of our existing tenant isolation to further ensure your investigation data and configurations remain separate from other customers **Bug Fixes** * **Authentication Security Update**: Migrated to PyJWT to address CVE-2024-23342, a token validation vulnerability that could potentially affect session security * **Investigation Confidence**: Resolved calculation errors that could show investigations as less confident than they actually were based on the evidence gathered * **Investigation Result Display**: Fixed a race condition that would occasionally prevent investigation results from displaying after completion * **Large Log Processing**: Reduced maximum log processing size to prevent timeouts when analyzing very verbose application logs