# DATAPLANE-EXPORTER KNOWLEDGE BASE

## OVERVIEW

`dataplane-exporter` is an internal service for dataplane-scoped metrics exporting. It serves `/metrics` and `/healthz`, computes metric snapshots at scrape time, and keeps business attribution logic separate from raw Kubernetes data collection.

This file is a map, not a tutorial.

→ **Current service scope**: [`README.md`](README.md)
→ **Parent internal service map**: [`../AGENTS.md`](../AGENTS.md)

## STRUCTURE

- `cmd/exporter/`: process entrypoint, flag parsing, HTTP server wiring.
- `pkg/runtime/`: exporter interface plus `/metrics` and `/healthz` server assembly.
- `pkg/source/kubernetes/`: controller-runtime based node/pod/namespace/resource-quota source and lightweight source models.
- `pkg/attribution/nodecomponent/`: node ownership and component attribution rules.
- `pkg/exporter/componentnodevcpu/`: typed snapshot, live reader, Prometheus exporter, and tests for node vCPU metrics.
- `pkg/exporter/resourcepoolcpulimit/`: typed snapshot, live reader, Prometheus exporter, and tests for resource pool CPU limit metrics.
- `pkg/diagnostics/`: self-observability helpers.
- `deploy/`: deployment and RBAC manifests.
- `Makefile`, `.golangci.yml`, `Dockerfile`: local build, lint, and image workflow.

## WHERE TO LOOK

| Task | Location | Notes |
|------|----------|-------|
| Change HTTP flags or endpoints | `cmd/exporter/config.go`, `cmd/exporter/main.go`, `pkg/runtime/runtime.go` | `listen-addr`, `metrics-path`, `health-path` live here |
| Add or change scrape-time runtime behavior | `pkg/runtime/` | Registry is rebuilt per scrape; exporters register into a fresh registry |
| Change raw Kubernetes data loading | `pkg/source/kubernetes/` | Keep source models lightweight; do not leak `client-go` objects upward |
| Change node attribution semantics | `pkg/attribution/nodecomponent/` | Admin/worker split and billable ownership rules belong here |
| Change component node vCPU metrics | `pkg/exporter/componentnodevcpu/` | Reader builds snapshots; exporter only translates snapshot to Prometheus metrics |
| Change resource pool CPU limit metrics | `pkg/exporter/resourcepoolcpulimit/` | Reader joins namespace labels with shared pool vCPU ceiling resource quotas |
| Add a new exporter | `pkg/exporter/<name>/`, `cmd/exporter/main.go` | Follow `componentnodevcpu` pattern and register it in `mustBuildExporters()` |
| Update deploy manifests | `deploy/` | RBAC and deployment need to match source access/runtime flags |

## COMMANDS

Run from `internal/dataplane-exporter/`:

```bash
make build
make build-linux
make test
make lint
make lint-fix
make docker-build IMG=dataplane-exporter:local
```

## LOCAL GUARDRAILS

- Keep the layering intact: `source` gathers raw state, `attribution` applies business rules, `reader/snapshot` aggregates, `exporter` emits metrics.
- Do not move component ownership logic into Prometheus collectors or Kubernetes source adapters.
- Prefer typed snapshots per exporter; do not introduce a service-wide "universal snapshot" unless multiple exporters prove the need.
- This service is dataplane-facing and should not depend on regional service business state or shared databases.
- Follow the current test style: table-driven unit tests next to the package under test.
- If you add an exporter or change runtime behavior, update both this file and [`README.md`](README.md).

## RELATED SOURCES

| Document | Purpose |
|----------|---------|
| [`README.md`](README.md) | Current scope and near-term evolution |
| [`../AGENTS.md`](../AGENTS.md) | Parent `internal/` service map |