README
¶
AWS Cost Exporter
github.com/sakuya1998/aws-cost-exporter exports cached AWS billing data as target-scoped Prometheus metrics. It is an exporter, not a financial reconciliation system.
The current stable release is v0.3.0. It supports explicit multi-account targets, Cost Explorer, CUR 2.0 through Athena, Organizations, Budgets, Savings Plans and Reserved Instances summaries, Cost Anomaly Detection, and bounded tag costs. Prometheus does not call AWS during a Prometheus scrape; /metrics reads an immutable in-memory snapshot.
v1.0 stabilization is in progress on the existing v0.3 behavior; it does not add collectors. The work freezes public configuration, Prometheus, and HTTP contracts, documents the supported capacity and lifecycle, and strengthens security and release evidence. Track the v1 SLO and v1.0 release checklist. The current stable install commands remain v0.3.0 until all external release gates pass.
Quick start
Build locally:
make build
./aws-cost-exporter --config configs/aws-cost-exporter.example.yaml
Container:
docker pull ghcr.io/sakuya1998/aws-cost-exporter:0.3.0
docker compose up --build
Helm OCI chart:
helm install aws-cost-exporter \
oci://ghcr.io/sakuya1998/charts/aws-cost-exporter \
--version 0.3.0 \
--set config.data.targets[0].account_id=444455556666
Validate the exact production configuration and referenced environment variables before startup:
./aws-cost-exporter --config config.yaml --check-config
HTTP endpoints
/metrics cached Prometheus metrics
/healthz process liveness
/ready required Cost Explorer snapshot readiness
/version build metadata
Documentation
- Documentation site
- English Wiki
- 简体中文 Wiki
- Example configuration
- IAM examples
- Grafana dashboard
- Prometheus rules
- Roadmap
- Contributing
- Security policy
The documentation site and Wiki are generated from docs/wiki on master. Submit documentation corrections through a pull request rather than editing the published copies directly.
Development
go test ./...
go test -race ./...
go vet ./...
golangci-lint run
make contract
Licensed under the Apache License 2.0.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
aws-cost-exporter
command
Package main provides the aws-cost-exporter executable entry point.
|
Package main provides the aws-cost-exporter executable entry point. |
|
internal
|
|
|
app
Package app composes and runs the aws-cost-exporter process.
|
Package app composes and runs the aws-cost-exporter process. |
|
aws/athena
Package athena implements the fixed-schema CUR 2.0 query provider.
|
Package athena implements the fixed-schema CUR 2.0 query provider. |
|
aws/budgets
Package budgets adapts allowlisted AWS Budgets to immutable domain values.
|
Package budgets adapts allowlisted AWS Budgets to immutable domain values. |
|
aws/clientfactory
Package clientfactory constructs isolated AWS clients for explicit targets.
|
Package clientfactory constructs isolated AWS clients for explicit targets. |
|
aws/common
Package common centralizes bounded AWS SDK instrumentation and attempt policy.
|
Package common centralizes bounded AWS SDK instrumentation and attempt policy. |
|
aws/costexplorer
Package costexplorer constructs AWS Cost Explorer infrastructure clients.
|
Package costexplorer constructs AWS Cost Explorer infrastructure clients. |
|
aws/organizations
Package organizations adapts AWS Organizations to bounded domain metadata.
|
Package organizations adapts AWS Organizations to bounded domain metadata. |
|
cache/memory
Package memory provides a lock-free-read, copy-on-write snapshot cache.
|
Package memory provides a lock-free-read, copy-on-write snapshot cache. |
|
collector
Package collector defines cost collection plugins and their registry.
|
Package collector defines cost collection plugins and their registry. |
|
collector/account
Package account collects linked-account daily and month-to-date costs.
|
Package account collects linked-account daily and month-to-date costs. |
|
collector/budget
Package budget collects target allowlisted AWS Budgets.
|
Package budget collects target allowlisted AWS Budgets. |
|
collector/forecast
Package forecast collects the current UTC month's remaining forecast.
|
Package forecast collects the current UTC month's remaining forecast. |
|
collector/organizationmeta
Package organizationmeta collects target Organizations account metadata.
|
Package organizationmeta collects target Organizations account metadata. |
|
collector/region
Package region collects region-grouped daily and month-to-date costs.
|
Package region collects region-grouped daily and month-to-date costs. |
|
collector/service
Package service collects service-grouped daily and month-to-date costs.
|
Package service collects service-grouped daily and month-to-date costs. |
|
collector/total
Package total collects ungrouped daily and month-to-date costs.
|
Package total collects ungrouped daily and month-to-date costs. |
|
config
Package config defines the exporter's strongly typed configuration.
|
Package config defines the exporter's strongly typed configuration. |
|
domain/anomaly
Package anomaly contains bounded Cost Anomaly Detection summaries.
|
Package anomaly contains bounded Cost Anomaly Detection summaries. |
|
domain/budget
Package budget defines immutable AWS Budget observations.
|
Package budget defines immutable AWS Budget observations. |
|
domain/commitment
Package commitment contains bounded Savings Plans and Reserved Instance utilization/coverage summaries.
|
Package commitment contains bounded Savings Plans and Reserved Instance utilization/coverage summaries. |
|
domain/cost
Package cost contains AWS cost domain values and their invariants.
|
Package cost contains AWS cost domain values and their invariants. |
|
domain/identity
Package identity defines stable target and collector identities.
|
Package identity defines stable target and collector identities. |
|
domain/organization
Package organization defines bounded AWS Organizations metadata.
|
Package organization defines bounded AWS Organizations metadata. |
|
domain/snapshot
Package snapshot owns the immutable multi-domain application snapshot.
|
Package snapshot owns the immutable multi-domain application snapshot. |
|
domain/tagcost
Package tagcost contains bounded tag cost observations.
|
Package tagcost contains bounded tag cost observations. |
|
httpserver
Package httpserver exposes metrics and bounded operational endpoints.
|
Package httpserver exposes metrics and bounded operational endpoints. |
|
logging
Package logging constructs structured loggers with mandatory redaction.
|
Package logging constructs structured loggers with mandatory redaction. |
|
metrics
Package metrics exposes immutable application snapshots to Prometheus.
|
Package metrics exposes immutable application snapshots to Prometheus. |
|
ports
Package ports defines infrastructure capabilities required by application code.
|
Package ports defines infrastructure capabilities required by application code. |
|
scheduler
Package scheduler coordinates periodic collector refreshes.
|
Package scheduler coordinates periodic collector refreshes. |
|
version
Package version exposes build metadata injected by the release toolchain.
|
Package version exposes build metadata injected by the release toolchain. |
|
tools
|
|
|
pages
command
|
Click to show internal directories.
Click to hide internal directories.