tracer-cloud--opensre/docs/temporal.mdx

---
title: "Temporal"
description: "Connect Temporal so OpenSRE can inspect workflow executions, event history, and worker health during investigations"
---

OpenSRE queries Temporal's HTTP API to retrieve workflow executions, event history, task queue health, and namespace-level metrics — helping diagnose workflow failures, activity retries, and worker outages.

<Note>
OpenSRE connects to Temporal's **HTTP API** (the `/api/v1/...` REST interface served
by the frontend service). This is a **self-hosted** server feature, enabled with the
`--http-port` flag (dev server) or `frontend.httpPort` config.

**Temporal Cloud is not currently supported**: Cloud exposes only gRPC/mTLS endpoints
for workflow data and an HTTP *Ops API* for control-plane management — neither is the
frontend HTTP API this integration uses. Point OpenSRE at a self-hosted Temporal
deployment.
</Note>

## Prerequisites

- A self-hosted Temporal Server with the HTTP API enabled
- The HTTP API base URL (and an API key only if your deployment requires bearer auth)

<Warning>
Port `7233` is the **gRPC** frontend port and will **not** work as `base_url` — the
HTTP API listens on a **separate** port. On the dev server it is set with
`--http-port` (it otherwise defaults to a random free port). The examples below use
`7243`.
</Warning>

## Setup

### Option 1: Environment variables

```bash
export TEMPORAL_API_URL="http://localhost:7243"
export TEMPORAL_NAMESPACE="default"
export TEMPORAL_API_KEY=""   # only if your deployment requires bearer auth
```

### Option 2: Persistent store

Add to `~/.opensre/integrations.json`:

```json
{
  "version": 1,
  "integrations": [
    {
      "id": "temporal-prod",
      "service": "temporal",
      "status": "active",
      "credentials": {
        "base_url": "http://temporal-frontend:7243",
        "namespace": "default",
        "api_key": ""
      }
    }
  ]
}
```

| Field | Default | Description |
| --- | --- | --- |
| `base_url` | — | Temporal **HTTP API** base URL (the `--http-port` listener, not the gRPC `7233` port) |
| `namespace` | `default` | Temporal namespace to query |
| `api_key` | — | Bearer token, sent as `Authorization: Bearer <key>`. Leave empty for unauthenticated clusters |

## Self-hosted Temporal Server

Set `base_url` to the frontend's HTTP API endpoint. Ensure the HTTP API is enabled —
it is a distinct listener from the gRPC frontend (`frontend.httpPort` in static config,
or `--http-port` on the dev server).

### Quick local test with Docker

The `temporalio/temporal` image bundles the CLI and an embedded dev server. Pin the
HTTP port explicitly (it is random by default) and bind to all interfaces so it is
reachable from the host:

```bash
docker run --rm \
  --name temporal-dev \
  -p 7233:7233 \
  -p 8233:8233 \
  -p 7243:7243 \
  temporalio/temporal:latest \
  server start-dev \
    --ip 0.0.0.0 \
    --http-port 7243
```

| Port | Purpose |
| --- | --- |
| `7233` | gRPC frontend (SDKs, `temporal` CLI) |
| `8233` | Web UI (`http://localhost:8233`) |
| `7243` | **HTTP API** — set this as `base_url` |

Confirm the HTTP API is answering before configuring the integration:

```bash
curl -s http://localhost:7243/api/v1/namespaces/default
```

Then verify the integration end to end:

```bash
opensre integrations verify temporal
```

## Investigation tools

When OpenSRE investigates a Temporal-related alert, four diagnostic tools are available:

| Tool | What it does |
| --- | --- |
| **Namespace info** | Retrieves namespace state and workflow execution counts grouped by status (Running, Failed, TimedOut) |
| **Workflows** | Lists recent workflow executions with status, type, task queue, and timing |
| **Workflow history** | Fetches the event history for a specific execution — shows the sequence of started, failed, and completed events |
| **Task queue** | Describes a task queue's active pollers and backlog stats (queue depth, add/dispatch rates) |

### Typical investigation flow

1. **Namespace info** — get a high-level picture: how many workflows are running vs failed?
2. **Workflows** — filter to failed/timed-out executions, identify the affected workflow type and task queue
3. **Workflow history** — drill into a specific execution to find which activity failed and why
4. **Task queue** — check if workers are polling and whether the queue has a growing backlog

## Troubleshooting

| Symptom | Fix |
| --- | --- |
| **Connection refused / protocol errors** | You may be pointing at the gRPC port. Use the HTTP API port (`--http-port`, e.g. `7243`), not `7233` |
| **404 on `/api/v1/...`** | The HTTP API may not be enabled — confirm `--http-port` (dev) or `frontend.httpPort` (static config) is set |
| **401 Unauthorized** | The cluster requires auth — set `api_key` to a valid bearer token |
| **404 Namespace not found** | Confirm the `namespace` value matches exactly (case-sensitive) |
| **Empty workflow list** | Workflows may have passed retention — check namespace retention settings |
| **No pollers on task queue** | Workers may be down — check worker deployment health |

## Security best practices

- Use a **read-only API key** where your deployment supports scoped auth — OpenSRE never writes to Temporal.
- Restrict network access to the HTTP API to trusted IPs.
- Store credentials in `~/.opensre/integrations.json` or environment variables, not in source code.