# Send StatsD metrics from an app

Send StatsD lines from an app's containers to the agent on their machine, which publishes them as custom metrics every minute.

The agent on every machine of a deployed app listens on UDP port 8125 for the containers on that
machine; nothing outside the machine can reach it. Every minute it publishes what it aggregated as
custom metrics under the namespace `App/<app name>`, with an `instance` dimension naming the
machine. It publishes with the app's own credentials, so you grant nothing for it.

## Prerequisites

- A deployed app (see [What is Apps?](/docs/deploy/guide/what-is)). Nothing else: no IAM
  permission of yours is used.
- Room in the **Custom metric series** quota (see [Quotas](quotas.md)).

## Send the lines

**Console:** not available. StatsD is sent from your application's code.
**CLI:** not available. StatsD is sent from your application's code.
**API**
From a container, send to `host.containers.internal:8125`:

```sh
echo "orders_placed:1|c|#region:eu" | nc -u -w0 host.containers.internal 8125
```

| Line                           | Kind                           | What is published each minute                                                               |
| ------------------------------ | ------------------------------ | ------------------------------------------------------------------------------------------- |
| `name:value\|c[\|@rate]`       | Counter                        | The sum of the increments, divided by the sample rate                                       |
| `name:value\|g`                | Gauge                          | The last value; `+n` and `-n` adjust it                                                     |
| `name:value\|ms`, `\|h`, `\|d` | Timer, histogram, distribution | The count, sum, minimum and maximum of the values; count and sum divided by the sample rate |
| `name:value\|s`                | Set                            | The number of distinct values                                                               |

DogStatsD tags (`|#key:value,…`) become dimensions; a line with more than nine tags is dropped, and
a tag named `instance` is ignored. Read
a counter's per-minute total with the **sum** statistic and a timer's average with **avg**. A gauge
is published every minute for ten minutes after its last update.

## Result

The series appear under **Monitoring**, **Custom metrics**, in the namespace `App/<app name>`,
within about a minute of the first line. Characters a namespace cannot hold are replaced with `-`.
Lines the agent could not parse or the platform refused are counted in the app's activity, with
the first reason.

## Related

- [Publish custom metrics](publish-custom-metrics.md)
- [Chart custom metrics](chart-custom-metrics.md)
- [Alarm on a custom metric](alarm-on-a-custom-metric.md)
