What is klag AGENTS.md?

Repository instructions for Klag, a Java service that reads Kafka consumer lag and exports metrics to monitoring systems. Consumer lag is the amount of work waiting to be processed in a Kafka stream.

Use it when changing Klag code, running its Java and Helm tests, building the fat JAR, or checking project-specific rules.

It tells coding agents how the project is structured, built, tested, and used without confusing the service with its documentation skill.

klag AGENTS.md — Instructions file for Codex and OpenCode by themoah: Repository instructions for Klag, a Java service that reads…

Install

Getting it into your agent

One page per mod, every tool's command on it. A separate URL per tool would split the same page into five that compete with each other.

agentmods

npx agentmods add instructions/themoah/klag/agents-md

Clone the repo

git clone --depth 1 https://github.com/themoah/klag

Made for: Codex, OpenCode.

Wrote this? Show the measurements

A badge with what this costs and how it scanned, read live from this page, so it follows the numbers instead of freezing them. Markdown for a README, HTML for a documentation site or a project page.

README.md

[![agentmods](https://agentmods.dev/badge/instructions/themoah/klag/agents-md.svg)](https://agentmods.dev/instructions/themoah/klag/agents-md)

Your own site

<a href="https://agentmods.dev/instructions/themoah/klag/agents-md"><img src="https://agentmods.dev/badge/instructions/themoah/klag/agents-md.svg" alt="Measured on agentmods" height="20"></a>

Per session 962 This file is loaded in full into every session.

When invoked 962 The same file — it is already loaded in full.

Security scan A 0 findings. Scan, not verified.

Origin original No closer match found in the catalogue.

Token cost

What it costs to keep this loaded

Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.

Model	Per session	Once invoked
Fable 5	$0.00962	$0.00962
Opus 5	$0.00481	$0.00481
Sonnet 5	$0.00192	$0.00192
Haiku 4.5	$0.00096	$0.00096

Measured yesterday against content hash 278b75e34049, method: parsed. Prices are Anthropic first-party input rates as of 2026-08-30, from the pricing page.

Security

Grade A, and why

klag AGENTS.md scanned grade A with 0 findings against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured yesterday.

A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.

Nothing flagged

None of the 26 patterns this scan looks for appear in this file: no shell pipes, no recursive deletes, no credential paths, no hidden text, no instruction-override or anti-refusal phrasing, no agent-config snooping. That is not a guarantee, it is the absence of the things that are checkable.

AGENTS.md · 72 lines

How it starts

The opening of the file, as written. The whole thing — 72 lines — stays where its author put it; the contents beside it link to each section on GitHub.

AGENTS.md

Instructions for AI coding agents working in this repository. CLAUDE.md is the detailed reference — architecture, every environment variable, every metric. Read it before changing code; this file is the short version plus the rules that are easy to violate.

What this is

Klag — a Kafka consumer lag exporter. Java 21 on Vert.x 4.5.30, Micrometer for metrics, Apache-2.0. It polls Kafka's AdminClient read-only and exports lag and derived signals to Prometheus, Datadog, or OTLP. Docs: https://klag.dev (machine-readable at https://klag.dev/llms.txt).

Are you trying to use Klag rather than develop it — install it, connect it, read its metrics? Then you want the skill, not this repo: /plugin marketplace add themoah/klag, or fetch https://klag.dev/.well-known/agent-skills/index.json. There is also a read-only documentation MCP server at https://klag.dev/mcp.

Build and test

Java 21 required (sdk use java 21.0.9-tem). Use ./gradlew locally; CI calls gradle directly, as no wrapper JAR is committed.

./gradlew compileJava
./gradlew test
./gradlew assemble              # fat JAR
./scripts/test-helm-chart.sh    # chart templating, offline
./scripts/check-plugin.sh       # plugin manifest shape
cd website && npm run build && npm test   # docs site + generators

./scripts/e2e-test.sh and ./scripts/e2e-strimzi-test.sh spin up real clusters — slow, and they need Docker. Do not run them speculatively.

Invariants — do not break these

Admin request volume must stay independent of topic count. Each collection cycle fetches committed offsets per group, then makes one batched getLogEndOffsets(Set) call for the union of their topics. Reintroducing a per-topic fetch turns one call into four requests × every topic × every cycle. MetricsCollectorBatchingTest pins this.
Deleted topics are filtered before describeTopics. One unknown topic fails the whole batch, and committed offsets outlive a deleted topic for offsets.retention.minutes. A failed listTopics must propagate, never fall through unfiltered.
Partial cycles skip stale-gauge cleanup but still publish the MCP snapshot. Cleaning against an incomplete key set would delete live series. An empty snapshot is never published.
Adding a metric means updating dashboard/demo-dashboard.json and the metrics tables in CLAUDE.md and website/src/content/docs/metrics/.
Version bumps. One bump of version in build.gradle.kts per PR that changes the application, and charts/klag/Chart.yaml appVersion plus the artifacthub annotation must match it. Website-only or docs-only changes do not bump.

Read the full file on GitHub · 72 lines

Changes

What this file has done since we first saw it

Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.

yesterday First seen · 72 lines · 962 tokens per session scan A 278b75e34049

Subscribe to this mod's changes

klag AGENTS.md is an instructions file published in the GitHub repository themoah/klag (82 stars, last pushed 4d ago), licensed Apache-2.0. It adds 962 tokens to every session, about $0.0048 per session on Opus 5. A static security scan graded it A with 0 findings. No closer match exists in the catalogue, so it is treated as the original; first seen 2026-09-03.

Analytics and metrics DevOps and cloud kafka kafka-consumer monitoring

klag AGENTS.md

Getting it into your agent

Wrote this? Show the measurements

What it costs to keep this loaded

Grade A, and why

Nothing flagged

How it starts

AGENTS.md

What this is

Build and test

Invariants — do not break these

What this file has done since we first saw it

Other instructions, from other repositories

kafka-backup CLAUDE.md

RuView AGENTS.md

netdata AGENTS.md

worldmonitor AGENTS.md

nvidia_gpu_exporter AGENTS.md

netdata CLAUDE.md