# Observability in Catalyst

Catalyst ships with built-in observability for every workload running on the platform — no instrumentation required. From the Catalyst console, inspect workflow executions step-by-step, drill into agent runs, and browse API-level request logs with token usage for LLM calls. You also get topology and metrics across your project out of the box.

:::tip Open in the Catalyst console

Every feature on this page — metrics, API logs, workflow replay, agent executions, and the topology — is available in the Catalyst Web UI at [catalyst.diagrid.io](https://catalyst.diagrid.io).

:::

:::info Local development

For local workflow and actor inspection during development, use the [Dapr Dev Dashboard](https://docs.diagrid.io/develop/local-development/dev-dashboard). The observability features on this page apply to workloads hosted on Catalyst.

:::

- Metrics — Request counts, latencies, error rates, and resource utilization per project and app.
- API Logs — Request/response inspection for every API call, including LLM token usage.
- Workflow Replay — Step-level drill-down, execution graph, and replay for durable workflows.

## Metrics dashboard

The console's **Metrics** page shows request counts, latencies, error rates, and resource utilization scoped by project and app. Use it to answer questions like:

- How many requests per second is my app receiving?
- What's the 95th-percentile (p95) latency of my pub/sub deliveries?
- Are any components returning errors?
- Am I close to project-level rate limits?

Metrics are retained according to your plan — on [Catalyst Cloud](https://docs.diagrid.io/operate/plans-and-support#limits-in-every-region), retention is 7 days by default; longer retention is available on paid plans.

## API Logs

**API Logs** are per-call records of every Dapr API request made through Catalyst, captured on the data plane:

- **Request and response bodies** (subject to body-size limits) for replay and debugging.
- **Status codes and latencies** for success/failure analysis.
- **LLM token usage** — `token_prompt`, `token_completion`, and `token_total` for calls through the Conversation API.
- **Originating app and component** for attribution.

API Logs are the fastest way to understand what your application actually sent to Catalyst — useful when an SDK wraps the call in ways that obscure the wire-level request, or when an LLM call returned an unexpected result.

### Observe app API logs

Observe app API logs directly from the CLI or console:

```bash
# Stream API logs for a given App ID
diagrid appid logs my-app --follow

# Fetch recent API logs for a given App ID
diagrid appid logs my-app --tail 500

# Fetch recent API logs for all App IDs in the current project
diagrid appid logs -a --tail 500
```

Run `diagrid appid logs --help` for all flags. For a paginated, project-wide view of the same logs, see [`diagrid project logs`](https://docs.diagrid.io/references/catalyst/cli-reference/project/logs).

In the console, open an app and select the **Logs** tab to view logs with filtering and search.

Log retention on [Catalyst Cloud](https://docs.diagrid.io/operate/plans-and-support#limits-in-every-region) is 3 days for the free tier and configurable on paid plans.

## Topology

The **Topology** view shows all resources in your project — the workloads (apps, agents, and MCP servers) and the components they use — including which workloads talk to which others and where pub/sub traffic flows. Use it to verify that services are wired up as expected and to spot unexpected cross-project dependencies.

## Distributed tracing

Catalyst emits OpenTelemetry traces for every Dapr API call. Export them to your preferred backend (Datadog, New Relic, Honeycomb, Jaeger, or any OTLP-compatible collector) by attaching a Configuration resource to your apps:

```yaml
apiVersion: cra.diagrid.io/v1beta1
kind: Configuration
metadata:
  name: tracing
spec:
  tracing:
    samplingRate: "1"
    otel:
      endpointAddress: "otel-collector.my-namespace.svc.cluster.local:4317"
      isSecure: false
      protocol: grpc
```

```bash
diagrid apply -f tracing-config.yaml
diagrid app update my-app --app-config tracing --wait
```

See [Declarative management](https://docs.diagrid.io/operate/project-operations/declarative-management) for the full `diagrid apply` workflow and [`diagrid app update`](https://docs.diagrid.io/references/catalyst/cli-reference/app/update) for binding configurations to apps. For Catalyst Enterprise Self-Hosted, the [observability guide](https://docs.diagrid.io/operate/hosting/enterprise-self-hosted/observability) covers platform-level telemetry exports.

## Audit logs

User and application audit logs capture who did what and when — for example, which user created an app, who rotated an API key, or which service account deployed a new component. Audit logs are available on Catalyst Enterprise plans and support compliance review. Contact Diagrid to enable audit log export on your organization.

## What's next

- [Develop Workflows](https://docs.diagrid.io/develop/workflows) — build workflows whose executions appear in the console.
- [Develop Agents](https://docs.diagrid.io/develop/agents) — build agents whose runs appear on the Agents page.
- [Catalyst Enterprise Self-Hosted Observability](https://docs.diagrid.io/operate/hosting/enterprise-self-hosted/observability) — OpenTelemetry export from the self-hosted data plane.
- [Plans & Support](https://docs.diagrid.io/operate/plans-and-support) — retention limits and SLAs per plan.