# Monitor Shadowing

> For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [streaming-full.txt](https://docs.redpanda.com/streaming-full.txt)

---
title: Monitor Shadowing
latest-redpanda-tag: v26.1.9
latest-console-tag: v3.7.3
latest-operator-version: v26.1.4
# EOL = End-of-Life (support lifecycle status)
page-is-nearing-eol: "false"
page-is-past-eol: "false"
page-eol-date: March 31, 2027
latest-connect-version: 4.93.0
docname: disaster-recovery/shadowing/monitor
page-component-name: streaming
page-version: "26.1"
page-component-version: "26.1"
page-component-title: Streaming
page-relative-src-path: disaster-recovery/shadowing/monitor.adoc
page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/disaster-recovery/shadowing/monitor.adoc
description: Monitor Shadowing health with status commands, metrics, and best practices for tracking replication performance.
page-git-created-date: "2025-11-19"
page-git-modified-date: "2026-01-06"
support-status: supported
---

<!-- Source: https://docs.redpanda.com/streaming/current/manage/disaster-recovery/shadowing/monitor.md -->

> 📝 **NOTE**
>
> This feature requires an [enterprise license](https://docs.redpanda.com/streaming/current/get-started/licensing/). To get a trial license key or extend your trial period, [generate a new trial license key](https://redpanda.com/try-enterprise). To purchase a license, contact [Redpanda Sales](https://redpanda.com/upgrade).
>
> If Redpanda has enterprise features enabled and it cannot find a valid license, [restrictions](https://docs.redpanda.com/streaming/current/get-started/licensing/#self-managed) apply.

Monitor your [shadow links](https://docs.redpanda.com/streaming/current/manage/disaster-recovery/shadowing/setup/) to ensure proper replication performance and understand your disaster recovery readiness. Use `rpk` commands, metrics, and status information to track shadow link health and troubleshoot issues.

> 📝 **NOTE**
>
> If you’re running Redpanda in Kubernetes, see [Monitor Kubernetes Shadow Links](https://docs.redpanda.com/streaming/current/manage/kubernetes/shadowing/k-monitor-shadowing/).

> ❗ **IMPORTANT: Experiencing an active disaster?**
>
> See [Failover Runbook](https://docs.redpanda.com/streaming/current/manage/disaster-recovery/shadowing/failover-runbook/) for immediate step-by-step disaster procedures.

## [](#status-commands)Status commands

To list existing shadow links:

```bash
rpk shadow list
```

To view shadow link configuration details:

```bash
rpk shadow describe <shadow-link-name>
```

For detailed command options, see [`rpk shadow list`](https://docs.redpanda.com/streaming/current/reference/rpk/rpk-shadow/rpk-shadow-list/) and [`rpk shadow describe`](https://docs.redpanda.com/streaming/current/reference/rpk/rpk-shadow/rpk-shadow-describe/). This command shows the complete configuration of the shadow link, including connection settings, filters, and synchronization options.

To check your shadow link status and ensure proper operation:

```bash
rpk shadow status <shadow-link-name>
```

-   **Shadow link state**: Overall operational state (`ACTIVE`, `PAUSED`).

-   **Individual topic states**: Current state of each replicated topic (`ACTIVE`, `FAULTED`, `FAILING_OVER`, `FAILED_OVER`, `PAUSED`).

-   **Task status**: Health of replication tasks across brokers (`ACTIVE`, `FAULTED`, `NOT_RUNNING`, `LINK_UNAVAILABLE`). For details about shadow link tasks, see [Shadow link tasks](https://docs.redpanda.com/streaming/current/manage/disaster-recovery/shadowing/overview/#shadow-link-tasks).

-   **Lag information**: Replication lag per partition showing source vs shadow high watermarks (HWM).


## [](#shadow-link-metrics)Metrics

Shadowing provides comprehensive metrics to track replication performance and health with the [`public_metrics`](https://docs.redpanda.com/streaming/current/reference/public-metrics-reference/) endpoint.

| Metric | Type | Description |
| --- | --- | --- |
| redpanda_shadow_link_shadow_lag | Gauge | The lag of the shadow partition against the source partition, calculated as source partition LSO (Last Stable Offset) minus shadow partition HWM (High Watermark). Monitor by shadow_link_name, topic, and partition to understand replication lag for each partition. |
| redpanda_shadow_link_total_bytes_fetched | Count | The total number of bytes fetched by a sharded replicator (bytes received by the client). Labeled by shadow_link_name and shard to track data transfer volume from the source cluster. |
| redpanda_shadow_link_total_bytes_written | Count | The total number of bytes written by a sharded replicator (bytes written to the write_at_offset_stm). Uses shadow_link_name and shard labels to monitor data written to the shadow cluster. |
| redpanda_shadow_link_client_errors | Count | The number of errors seen by the client. Track by shadow_link_name and shard to identify connection or protocol issues between clusters. |
| redpanda_shadow_link_shadow_topic_state | Gauge | Number of shadow topics in the respective states. Labeled by shadow_link_name and state to monitor topic state distribution across your shadow links. |
| redpanda_shadow_link_total_records_fetched | Count | The total number of records fetched by the sharded replicator (records received by the client). Monitor by shadow_link_name and shard to track message throughput from the source. |
| redpanda_shadow_link_total_records_written | Count | The total number of records written by a sharded replicator (records written to the write_at_offset_stm). Uses shadow_link_name and shard labels to monitor message throughput to the shadow cluster. |

See also: [Public Metrics](https://docs.redpanda.com/streaming/current/reference/public-metrics-reference/)

## [](#monitoring-best-practices)Monitoring best practices

### [](#health-check-procedures)Health check procedures

Establish regular monitoring workflows to ensure shadow link health:

```bash
# Check all shadow links are active
rpk shadow list | grep -v "ACTIVE" || echo "All shadow links healthy"

# Monitor lag for critical topics
rpk shadow status <shadow-link-name> | grep -E "LAG|Lag"
```

### [](#alert-conditions)Alert conditions

Configure monitoring alerts for the following conditions, which indicate problems with Shadowing:

-   **High replication lag**: When `redpanda_shadow_link_shadow_lag` exceeds your RPO requirements

-   **Connection errors**: When `redpanda_shadow_link_client_errors` increases rapidly

-   **Topic state changes**: When topics move to `FAULTED` state

-   **Task failures**: When replication tasks enter `FAULTED` or `NOT_RUNNING` states

-   **Throughput drops**: When bytes/records fetched drops significantly

-   **Link unavailability**: When tasks show `LINK_UNAVAILABLE` indicating source cluster connectivity issues


For more information about shadow link tasks and their states, see [Shadow link tasks](https://docs.redpanda.com/streaming/current/manage/disaster-recovery/shadowing/overview/#shadow-link-tasks).