amp_push
A small, dependency-light client for pushing metrics to
AWS Managed Prometheus (AMP) via
SigV4-signed Prometheus remote_write.
For callers that want to send a handful of metrics directly - a CI job, a one-off script, a Lambda - without standing up a collector or a sidecar.
Full docs (installation, quickstart, API reference): https://amp-push.readthedocs.io/
Why amp_push
The normal way to get metrics into AMP is to run something that speaks
remote_write continuously: the ADOT/OpenTelemetry Collector, a Prometheus
server, a sidecar scraping /metrics off your process. That's the right
call when you have a long-running service and want it continuously scraped.
It's a lot of moving parts for the other case: something that runs briefly,
emits a handful of data points, and exits - a Lambda invocation, a CI job, a
cron script on a box that isn't otherwise running anything. There's no
/metrics endpoint for anyone to scrape, because there's no process left to
scrape it from by the time anyone would look. Standing up a collector to
receive a push from one process, for a few data points, isn't proportionate
to the job.
amp_push is for that gap: call client.push([...]) at the point in your
code where something worth measuring just happened, and it's in AMP a
network round-trip later. No local aggregation, no background thread, no
extra thing to deploy or keep running - just one signed HTTP POST.
Example use cases
(Illustrative scenarios below - not real deployments, just the shape of
problem amp_push fits.)
- A nightly ETL Lambda.
etl-dailyruns once a night, processes a batch of records, and exits. It has no business running a metrics sidecar for the two minutes it's alive - it just callsclient.push(...)withjob_duration_secondsandrows_processedright before returning, so the run shows up in the same Grafana dashboards as everything else. - A CI test suite. A GitHub Actions job pushes
test_suite_duration_secondsandtests_failed_total(labelled by branch) at the end of every run, so a team can graph flakiness and runtime creep over weeks without instrumenting a long-lived exporter anywhere - the runner doesn't exist after the job ends. - A one-off backfill script. An engineer runs a migration script from
their laptop against an assumed IAM role, and it reports
rows_migrated_totalonce at the end - useful signal for "did this actually run to completion", without setting up anything that outlives the script. - An image-processing Lambda. Each invocation resizes one uploaded image
and increments
images_processed_totalorimages_failed_totalbefore returning - one metric push per invocation, no collector layer added to every function in the pipeline just to get a failure count.
Installation
uv add amp_push
# or
pip install amp_push
Usage
from amp_push import AMPClient, Metric
client = AMPClient(workspace_id="ws-xxxx", region="us-east-1")
metric = Metric("job_duration_seconds", 12.4, labels={"job": "etl-daily"})
client.push([metric])
That's the whole API: one class, one type, one method.
Metric
Metric(name, value, labels={}, timestamp=datetime.now(UTC))
name- the metric name (must match[a-zA-Z_:][a-zA-Z0-9_:]*).value- afloat.labels- adict[str, str], optional. Label names must match[a-zA-Z_][a-zA-Z0-9_]*, and no value may be empty - omit a label rather than setting it to"". Don't set__name__yourself; it's derived fromname.timestamp- a timezone-awaredatetime, optional (defaults to now).
Invalid names/labels raise ValueError immediately, at construction time.
Each Metric you push is one isolated point at timestamp, not a
locally-accumulated running counter - amp_push doesn't track state between
calls. If you push the same metric name repeatedly (e.g. once per CI run),
query it in PromQL/Grafana with sum(...) or count_over_time(...) over the
range you care about, not rate()/increase(), which assume a single
process incrementing one series continuously.
AMPClient
AMPClient(*, workspace_id=None, workspace_alias=None, region, timeout=10.0, session=None)
All arguments are keyword-only.
workspace_id- the AMP workspace to write to, e.g."ws-xxxx". Look this up yourself (console,aws amp list-workspaces, Terraform output, ...), or passworkspace_aliasinstead and letamp_pushlook it up.workspace_alias- the workspace's alias (e.g."prod-services") instead of its id. Resolved viaamp:ListWorkspacesthe first time the id is actually needed (client.workspace_id,client.remote_write_url, orclient.push(...)) - not in the constructor - and cached on the client after that, so it's one extra API call perAMPClientinstance, not perpush(). RaisesValueErrorif no workspace has that exact alias, or if more than one does.- Exactly one of
workspace_id/workspace_aliasmust be given - passing both, or neither, raisesValueErrorimmediately. region- the AWS region the workspace is in.timeout- request timeout in seconds for the HTTP POST.session- an existingboto3.Sessionto sign with, if you need to control credential resolution yourself (an assumed role, a named profile, ...). Defaults toboto3.Session(), which uses boto3's normal credential chain (environment variables, shared config/credentials files, an attached role, ...).
client.push(metrics):
- Is a no-op for an empty list - no AWS calls, no HTTP request.
- Encodes
metricsas a PrometheusWriteRequest, compresses it with raw (non-framed) Snappy, signs it with SigV4 for theapsservice, and POSTs it toclient.remote_write_url. - Raises
RuntimeErrorif no AWS credentials can be resolved from the session. - Raises
requests.HTTPErrorif AMP rejects the request (wrong workspace, missingaps:RemoteWritepermission, malformed body, ...), or anotherrequests.RequestExceptionon a network-level failure (timeout, DNS, connection refused, ...).
There's no retry logic and no batching beyond "one WriteRequest per
push() call" - keep it simple, and add that in the caller if you need it.
Required IAM permission
Whatever credentials AMPClient signs with need aps:RemoteWrite on the
target workspace's ARN, e.g.:
{
"Effect": "Allow",
"Action": "aps:RemoteWrite",
"Resource": "arn:aws:aps:us-east-1:123456789012:workspace/ws-xxxx"
}
If you pass workspace_alias instead of workspace_id, the same
credentials also need aps:ListWorkspaces - that action doesn't support
resource-level scoping to one workspace, so it's granted on "*":
{
"Effect": "Allow",
"Action": "aps:ListWorkspaces",
"Resource": "*"
}
[!NOTE]
aps:ListWorkspacesis a separate permission fromaps:RemoteWriteand isn't implied by it. If a caller only hasaps:RemoteWrite, alias resolution fails with anAccessDeniedClientErrorfromlist_workspacesuntilaps:ListWorkspacesis granted too. Passingworkspace_iddirectly avoids needing this permission at all.
Design notes
- Hand-rolled protobuf encoding (
_wire_format.py, private). The four message shapesremote_writeneeds have been stable for years, so encoding them by hand avoids taking aprotoccodegen toolchain as a dependency. Verified byte-for-byte against the realprotobufruntime intests/test_wire_format.py(a dev-only dependency - it's not needed at runtime). - No custom exception hierarchy. Errors surface as whatever boto3/
botocore/
requestsalready raise, plus one plainRuntimeErrorfor "no credentials". Simple to reason about, nothing new to learn.
Documentation
The full docs (installation, quickstart, use cases, API reference) are
published at https://amp-push.readthedocs.io/, built with
Sphinx from docs/ via
.readthedocs.yaml - rebuilt automatically on every
push to main. To build them locally instead:
$ uv sync --all-extras
$ uv run sphinx-build -b html docs docs/_build/html
# then open docs/_build/html/index.html
Development
# Install dependencies (including dev/test extras)
$ uv sync --all-extras
# Run the tests
$ uv run pytest
# With coverage
$ uv run pytest --cov=amp_push
License
MIT - Copyright (c) 2026 Phil Hendren.
Metadata
Release files for amp-push 0.1.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| amp_push-0.1.1.tar.gz | 86.9 kB | With provenance | Details for amp_push-0.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| amp_push-0.1.1-py3-none-any.whl | Python 3 | none | any | Details for amp_push-0.1.1-py3-none-any.whl |
Total release size: 99.3 kB
Release files / amp_push-0.1.1.tar.gz
| Download URL | amp_push-0.1.1.tar.gz |
|---|---|
| Size | 86.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
05f76cb9082f14bc845285ca8d682e061b0906adcbbb87883705cd370f3c2f98
|
|
BLAKE2b-256 checksum How to use checksums |
1ccd4c267ea6f88d3d77f7803f91fef6b2f0d5f3bd8daabb6d0ecf1cc68cc9c0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 5, 2026.
Transparency logRelease files / amp_push-0.1.1-py3-none-any.whl
| Download URL | amp_push-0.1.1-py3-none-any.whl |
|---|---|
| Size | 12.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
452c75b15c725c2f2f9482292d8330f4bac9f953c7ea567a98ff6c6f87bd3148
|
|
BLAKE2b-256 checksum How to use checksums |
39f9828389ffbeebd70898816456e466f4f9526b86fbfd248191b00952cb3441
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 5, 2026.
Transparency logSecurity for amp-push 0.1.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for amp_push-0.1.1.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 5, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.