debug

name	debug
description	Structured triage workflow for CarbonJ bugs — reproduce, isolate to a pipeline phase (ingest / accumulate / store / query), then write a failing test before patching.

/debug — CarbonJ bug triage

1. Reproduce

• Capture exact command, profile, and inputs that trigger the bug.
• If from production logs, note timestamps, metric names, and any cfgKinesis / cfgAccumulator overrides in effect.

2. Localize to a pipeline phase

CarbonJ is ingest → accumulate → store → query. Identify which phase failed:

Symptom	Likely phase	Where to look
Points dropped at the edge, line-protocol parse errors	ingest	engine/LineProtocolHandler, engine/PickleProtocolHandler, netty/, InputQueue, PointProcessor*
Kinesis lag, checkpoint stuck, KCL warnings	ingest (Kinesis)	engine/KinesisConsumer, KinesisRecordProcessor, cfgKinesis, FileCheckPointMgr, DynamoDbCheckPointMgr
Wrong rollup values, missing aggregated series	accumulate	accumulator/AccumulatorImpl, MetricAggregationRule, aggregation-rules-test.conf, recovery/
Glob queries return nothing / wrong ids	store/index	db/index/MetricIndexImpl, IndexStoreRocksDB, QueryUtils, QueryPart
Data missing in 5m or 30m archive	store/points	db/points/DataPointArchiveRocksDB, IntervalProcessor*, StagingFile*
HTTP 500 / wrong JSON shape	query	engine/Graphite*Servlet, admin/
Wrong routing between shards	relay	Relay, RelayRouter, RelayRules, relay-rules.conf, blacklist.conf

3. Read the matching cfg* class

The bean wiring for the phase is in the corresponding @Configuration class. Tunables almost always live there, not at the use site.

4. Write a failing test

Add a JUnit 5 test in the matching package under carbonj.service/src/test/java/.... Reuse fixtures from carbonj.service/src/test/resources/ (e.g. aggregation-rules-test.conf).

Run scoped:

./gradlew :carbonj.service:test --tests <FQCN>.<method> --info

5. Patch and verify

• Make the smallest change that turns the test green.
• Re-run the full module suite: ./gradlew :carbonj.service:test.
• Check license headers if you added new files: ./gradlew licenseMain.

Common gotchas

• Do not change the dbName values 60s24h, 5m7d, 30m2y — admin APIs depend on them.
• LocalStack/Testcontainers tests need Docker; if the bug is in kinesis/, you need it running locally.
• Releases must run from master; debug commits should land on a feature branch.