# linkerd viz: Install and Query Metrics

> linkerd viz installs the metrics extension and queries live traffic stats. Reference for install, check, stat, and the extension errors in CI.

Source: https://latchkey.dev/learn/command-reference/linkerd-viz  
Updated: 2026-06-30

linkerd viz is the observability extension: it installs a metrics stack and lets you query live success rates, RPS, and latency from the command line.

For a canary or smoke test, linkerd viz stat gives you real golden-signal numbers to assert on, without opening a dashboard.

## What it does

linkerd viz install renders the viz extension (metrics API, Prometheus, dashboard) to apply with kubectl. Once installed, linkerd viz stat reports success rate, requests per second, and latency percentiles per resource, and linkerd viz check validates the extension.

## Common usage

```Terminal
linkerd viz install | kubectl apply -f -
linkerd viz check
# live golden signals for deployments in a namespace
linkerd viz stat deploy -n my-app
```

## Options

| Subcommand / flag | What it does |
| --- | --- |
| install | Render the viz extension manifests |
| check | Validate the viz extension |
| stat <resource> | Show success rate, RPS, and latency |
| stat -n <ns> | Scope stats to a namespace |
| top / tap | Live per-request views for debugging |

## In CI

After a canary deploy, poll linkerd viz stat deploy/my-app -o json and fail the rollout if success rate drops below a threshold. Run linkerd viz check first so a broken metrics stack does not read as zero traffic.

## Common errors in CI

"Error: called Linkerd viz extension command but the Linkerd viz extension is not installed" means you ran stat/check before install. Empty or "-" values in stat mean no traffic has flowed yet or the workload is not meshed. "√ viz extension ... [FAIL]" from viz check points at a missing metrics pod.

## Using this in CI

A runner has no kubeconfig, no cached context, and no interactive auth. Every kubectl invocation in CI needs the context supplied explicitly, and most confusing CI failures here are the command running against the wrong cluster or no cluster at all.

```Terminal
# never rely on the ambient context on a runner
kubectl --context "$KUBE_CONTEXT" -n "$NAMESPACE" get pods

# confirm what you are actually connected to before mutating anything
kubectl config current-context
kubectl cluster-info

# fail fast instead of hanging on an unreachable API server
kubectl --request-timeout=30s get nodes
```

> Always set `--request-timeout` in CI. Without it an unreachable API server hangs until the job times out, which turns a thirty-second failure into a twenty-minute one.

## FAQ

### linkerd viz: Install and Query Metrics?

For a canary or smoke test, linkerd viz stat gives you real golden-signal numbers to assert on, without opening a dashboard.

### What it does?

linkerd viz install renders the viz extension (metrics API, Prometheus, dashboard) to apply with kubectl. Once installed, linkerd viz stat reports success rate, requests per second, and latency percentiles per resource, and linkerd viz check validates the extension.

### In CI?

After a canary deploy, poll linkerd viz stat deploy/my-app -o json and fail the rollout if success rate drops below a threshold. Run linkerd viz check first so a broken metrics stack does not read as zero traffic.

### Common errors in CI?

"Error: called Linkerd viz extension command but the Linkerd viz extension is not installed" means you ran stat/check before install. Empty or "-" values in stat mean no traffic has flowed yet or the workload is not meshed. "√ viz extension ... [FAIL]" from viz check points at a missing metrics pod.

---

Latchkey runs CI/CD that repairs its own failures. Agent entry points: https://latchkey.dev/agent.txt, https://latchkey.dev/openapi.json, https://latchkey.dev/llms.txt