Skip to main content

OpenTelemetry Quickstart Guide

This quickstart guide will help you get Causely up and running with OpenTelemetry. This setup is ideal if you're already using OpenTelemetry instrumentation or want to use your existing OpenTelemetry Collector.

1

Get Your Installation Command​

  1. Log in to the Causely portal.
  2. Visit the mediators page.
  3. Click the "Add new" button (or "Add ➕" button) on the mediators page.
  4. In the instructions panel, you'll see the Helm installation command with your access token pre-filled.
  5. Copy the complete Helm command. It will look similar to the example below.
Example Command

The command you copy will include your specific access token and cluster name. Here's what it typically looks like:

export CAUSELY_TOKEN=<your_token>
export CAUSELY_CLUSTER_NAME=<your_cluster_name>
export CAUSELY_VERSION=<version>
helm upgrade --install causely \\
  --create-namespace oci://us-docker.pkg.dev/public-causely/public/causely \\
  --version "${CAUSELY_VERSION}" \\
  --namespace=causely \\
  --set image.tag="${CAUSELY_VERSION}" \\
  --set global.cluster_name="\${CAUSELY_CLUSTER_NAME}" \\
  --set mediator.gateway.token="\${CAUSELY_TOKEN}"
Screenshot Placeholder

Screenshots of the mediators page, "Add new" button, and instructions panel will be added here.

4

Create a Values File to Configure OpenTelemetry​

Create a causely-values.yaml file with the following configuration to disable eBPF instrumentation and configure OpenTelemetry:

global:
  cluster_name: <your_cluster_name>
mediator:
  gateway:
    token: <your_token>
scrapers:
  bpf:
    enabled: false

Replace <your_cluster_name> and <your_token> with your actual values from the portal.

5

Run the Installation Command​

  1. Open a terminal with kubectl configured to access your cluster.
  2. Run the Helm command with your values file:
export CAUSELY_VERSION=<version>
helm upgrade --install causely \\
  --create-namespace oci://us-docker.pkg.dev/public-causely/public/causely \\
  --version "${CAUSELY_VERSION}" \\
  --namespace=causely \\
  --set image.tag="${CAUSELY_VERSION}" \\
  --set global.cluster_name="<your_cluster_name>" \\
  --set mediator.gateway.token="<your_token>" \\
  --values causely-values.yaml
  1. Wait for the installation to complete:
kubectl wait --for=condition=Ready pod -l app.kubernetes.io/part-of=causely -n causely --timeout=300s
6

Configure Your OpenTelemetry Collector​

Now you need to configure your OpenTelemetry Collector to send traces and metrics to Causely's mediator. The mediator listens for OpenTelemetry Protocol (OTLP) data on port 4317.

If you don't have an OpenTelemetry Collector running, you can install one using the OpenTelemetry Operator. For detailed configuration instructions, see the OpenTelemetry integration guide.

The key configuration you'll need is to add an exporter that points to the Causely mediator:

exporters:
  otlp/causely:
    endpoint: mediator.causely:4317
    compression: none
    tls:
      insecure: true
7

What to Expect​

Once configured, Causely will:

  • Receive OpenTelemetry data: Your OpenTelemetry Collector will send traces and metrics to the Causely mediator.
  • Discover service dependencies: Causely will automatically discover service dependencies from your OpenTelemetry traces.
  • Show data in the UI: Within a few minutes, you should start seeing services and their relationships appearing in the Causely UI at https://portal.causely.app.
tip

For complete OpenTelemetry configuration examples, including Kubernetes attributes processing and filtering, see the OpenTelemetry integration documentation.

8

Add More Telemetry Sources​

To help Causely infer Diagnoses more effectively, connect additional telemetry sources. Visit the Telemetry Sources page to learn about the data sources that Causely supports, including:

9

Review Discovery​

You have successfully installed Causely! Navigate to https://portal.causely.app to verify your environment has been discovered. You should see entities populated in the Topology view:

Topology View

If the entities and connections you are expecting to see are not appearing, go to the Integrations page and check for any errors for the telemetry sources you have configured.

Integration Errors

Errors in the integrations page will prevent Causely from discovering entities and connections in your environment. Follow the troubleshooting steps to resolve the errors.

10

Connect Causely to AI Agents​

Give your agents access to Causely's causal model via the MCP server. Any MCP-compatible agent or assistant including Claude Code, Cursor, VS Code, HolmesGPT, or your own custom agent, can query root causes, service health, dependency maps, and reliability reports directly.

Visit the agent integration page to get started.

Other Platforms Supported

While this quickstart guide focuses on Kubernetes, Causely also supports:

  • Container Orchestration: Nomad, Docker, ECS
  • GitOps: Argo CD, Flux
  • Virtual Machines: Direct installation on VMs

For detailed installation instructions for these platforms, visit the Installation Overview page.