---
name: clinic-continuous-profiling
description: |
  Continuous profiling metadata and profile downloads through clinic-cli.
---

# Continuous profiling

Use the parent CLI commands:

```text
python3 .opencode/skills/builtin/clinic-cli/scripts/clinic_cli.py continuous-profiling --help
python3 .opencode/skills/builtin/clinic-cli/scripts/clinic_cli.py continuous-profiling-download --help
```

List profile groups or a profile snapshot:

```text
python3 .opencode/skills/builtin/clinic-cli/scripts/clinic_cli.py continuous-profiling \
  --cluster-id <cluster_id> \
  --start <start_unix> \
  --end <end_unix>
```

For BYOC, the CLI automatically splits longer inventory ranges into API-safe
sub-windows (the upstream API rejects minute-rounded windows of 10,800 seconds
or more). Use `--start` and `--end`; `--from` and `--to` are not supported.

Download a profile blob:

```text
python3 .opencode/skills/builtin/clinic-cli/scripts/clinic_cli.py continuous-profiling-download \
  --cluster-id <cluster_id> \
  --ts <snapshot_ts> \
  --profile-type cpu \
  --component tidb \
  --address <instance_address> \
  --unzip
```

The command output returns the downloaded path.

## Profile types

| Type | Use for |
| --- | --- |
| `cpu` | CPU hotspots and hot functions. |
| `heap` | Memory allocation and retained heap. |
| `mutex` | Lock contention. |
| `goroutine` | Blocked or leaked goroutines. |

## Availability notes

- Dedicated clusters commonly support continuous profiling.
- For a logical BYOC ID, `continuous-profiling` resolves the physical
  `byoc-host` ID and returns read-only group/target inventory.
- BYOC canonical APIs do not expose action tokens, profile bytes, view, config,
  or download. `continuous-profiling-download` therefore fails explicitly for
  BYOC; do not retry through the Dedicated NGM route.
- Premium profiling can be tied to the parent resource pool rather than the tenant cluster record.
- Empty results may mean the cluster tier, time window, component, or profile type is unsupported.

## Analysis notes

- Use profiling after metrics show sustained CPU, memory, lock, or goroutine symptoms.
- For TiDB high CPU, check GC metrics first; if GC is abnormal, continuous profiling is the next confirmation step.
- For downloaded pprof data, summarize hot packages/functions and relate them back to metrics and SQL evidence.
- Do not paste customer SQL or sensitive identifiers from profile labels unless necessary and safe.