> ## Documentation Index
> Fetch the complete documentation index at: https://otel.fyi/llms.txt
> Use this file to discover all available pages before exploring further.

# Podman

> OpenTelemetry receiver for Podman

# Podman Receiver

![Status](https://img.shields.io/badge/status-alpha-red)

**Available in:** `contrib`

**Maintainers:** [@rogercoll](https://github.com/rogercoll)

**Source:** [opentelemetry-collector-contrib](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/podmanreceiver)

## Supported Telemetry

![Metrics](https://img.shields.io/badge/metrics-alpha-green)

## Overview

> :information\_source: Requires Podman API version 3.3.1+ and Windows is not supported.

## Configuration

The following settings are required:

* `endpoint` (default = `unix:///run/podman/podman.sock`): Address to reach the Podman service API.

> \[!NOTE]
> Podman runs in rootless mode by default. For rootless Podman, use the user socket path:
> `unix:///run/user/<UID>/podman/podman.sock` (or `unix://$XDG_RUNTIME_DIR/podman/podman.sock`).
> The default path `/run/podman/podman.sock` is for rootful (system) Podman and requires elevated permissions.

The following settings are optional:

* `collection_interval` (default = `10s`): The interval at which to gather container stats.
* `initial_delay` (default = `1s`): defines how long this receiver waits before starting.
* `timeout` (default = `5s`): The maximum amount of time to wait for Podman API responses.
* `metrics` (defaults at [./documentation.md](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/podmanreceiver/documentation.md)): Enables/disables individual metrics. See [./documentation.md](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/podmanreceiver/documentation.md) for full detail.

Example:

### Rootful

```yaml theme={null}
receivers:
  podman_stats:
    endpoint: unix:///run/podman/podman.sock
    timeout: 10s
    collection_interval: 10s
    initial_delay: 1s
    metrics:
      container.cpu.usage.system:
        enabled: false
```

### Rootless

```yaml theme={null}
receivers:
  podman_stats:
    endpoint: unix:///run/user/<UID>/podman/podman.sock
    timeout: 10s
    collection_interval: 10s
    initial_delay: 1s
    metrics:
      container.cpu.usage.system:
        enabled: false
```

Where `<UID>` is your user ID.

The full list of settings exposed for this receiver are documented in [config.go](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/podmanreceiver/config.go)
with detailed sample configurations in [testdata/config.yaml](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/podmanreceiver/testdata/config.yaml).

### Connecting over SSH

```yaml theme={null}
receivers:
  podman_stats:
    endpoint: ssh://core@localhost:53841/run/user/1000/podman/podman.sock
    ssh_key: /path/to/ssh/private/key
    ssh_passphrase: <password>
```

### Podman API compatibility

The receiver has only been tested with API 3.3.1+ but it may work with older versions as well. If you want to use the
receiver with an older API version, please set the `api_version` to the desired version. For example,

```yaml theme={null}
receivers:
  podman_stats:
    endpoint: unix:///run/podman/podman.sock
    api_version: 3.2.0
```

## Metrics

The receiver emits the following metrics:

container.memory.usage.limit
container.memory.usage.total
container.memory.percent
container.network.io.usage.tx\_bytes
container.network.io.usage.rx\_bytes
container.blockio.io\_service\_bytes\_recursive.write
container.blockio.io\_service\_bytes\_recursive.read
container.cpu.usage.system
container.cpu.usage.total
container.cpu.percent
container.cpu.usage.percpu

See [./documentation.md](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/podmanreceiver/documentation.md) for full detail.

## Building

This receiver uses the official libpod Go bindings for Podman. In order to include
this receiver in your build, you'll need to make sure all non-Go dependencies are
satisfied or some features are excluded. You can use the below mentioned build tags to
exclude the non-Go dependencies. This receiver does not use any features enabled
by these deps so excluding these does not affect the functionality in any way.

Recommended build tags to use when including this receiver in your build:

* `containers_image_openpgp`
* `exclude_graphdriver_btrfs`
* `exclude_graphdriver_devicemapper`

## Metrics

| Metric Name                                            | Description                                                | Unit          | Type          | Attributes |
| ------------------------------------------------------ | ---------------------------------------------------------- | ------------- | ------------- | ---------- |
| ✅ `container.blockio.io_service_bytes_recursive.read`  | Number of bytes transferred from the disk by the container | \{operations} | Counter       |            |
| ✅ `container.blockio.io_service_bytes_recursive.write` | Number of bytes transferred to the disk by the container   | \{operations} | Counter       |            |
| ✅ `container.cpu.percent`                              | Percent of CPU used by the container.                      | 1             | Gauge         |            |
| ✅ `container.cpu.usage.percpu`                         | Total CPU time consumed per CPU-core.                      | s             | Counter       | core       |
| ✅ `container.cpu.usage.system`                         | System CPU usage.                                          | s             | Counter       |            |
| ✅ `container.cpu.usage.total`                          | Total CPU time consumed.                                   | s             | Counter       |            |
| ✅ `container.memory.percent`                           | Percentage of memory used.                                 | 1             | Gauge         |            |
| ✅ `container.memory.usage.limit`                       | Memory limit of the container.                             | By            | UpDownCounter |            |
| ✅ `container.memory.usage.total`                       | Memory usage of the container.                             | By            | UpDownCounter |            |
| ✅ `container.network.io.usage.rx_bytes`                | Bytes received by the container.                           | By            | Counter       |            |
| ✅ `container.network.io.usage.tx_bytes`                | Bytes sent by the container.                               | By            | Counter       |            |

## Attributes

| Attribute Name | Description                                         | Type   | Values |
| -------------- | --------------------------------------------------- | ------ | ------ |
| `core`         | The CPU core number when utilising per-CPU metrics. | string |        |

## Resource Attributes

| Attribute Name         | Description                                                                  | Type   | Enabled |
| ---------------------- | ---------------------------------------------------------------------------- | ------ | ------- |
| `container.id`         | The ID of the container.                                                     | string | ✅       |
| `container.image.name` | The name of the image in use by the container.                               | string | ✅       |
| `container.name`       | The name of the container.                                                   | string | ✅       |
| `container.runtime`    | The runtime of the container. For this receiver, it will always be 'podman'. | string | ✅       |

## Configuration

### Example Configuration

```yaml theme={null}
podman_stats:
podman_stats/all:
  endpoint: http://example.com/
  collection_interval: 2s
  timeout: 20s
podman_stats/empty_endpoint:
  endpoint: ""
podman_stats/invalid_collection_interval:
  collection_interval: 0s
```

***

*Last generated: 2026-07-06*