Skip to content

a-pavithraa/springboot-skills-marketplace / plugins/springboot-architecture/skills/spring-boot-team-harness

spring-boot-team-harness

Verified

Use when a team wants every developer's coding agent (Claude Code or Codex) to follow the same rules and coding conventions on a Maven or Gradle Spring Boot 4 repository: setting up AGENTS.md, coding standards, guardrails, shared agent settings, or build and CI checks that agents must pass before code merges. It adds ./mvnw verify or ./gradlew build gates that fail on null-safety bugs (NullAway with JSpecify), module-boundary breaches (Spring Modulith), unknown or deprecated Boot property keys, Spring mistakes that compile (ArchUnit) and unformatted code, Claude Code and Codex hooks that run those gates before a turn ends, and a CI workflow.

FileKindSize
SKILL.mdskill md20.3 KB
assets/gradle/harness.gradleother5.4 KB
assets/observability/HandledFailureFilter.javaother2.1 KB
assets/observability/InstallOpenTelemetryAppender.javaother877 B
assets/observability/LogLeakCheck.javaother3.3 KB
assets/observability/application-observability-defaults.ymlconfig1.9 KB
assets/observability/application-observability.ymlconfig445 B
assets/observability/check_dashboards.pyscript3.4 KB
assets/observability/check_request.pyscript6.6 KB
assets/observability/compose.observability.ymlconfig704 B
assets/observability/dashboards/jvm-resources.jsonconfig7.7 KB
assets/observability/dashboards/service-health.jsonconfig10.7 KB
assets/observability/grafana-provider.yamlconfig133 B
assets/observability/logback-spring.xmlconfig736 B
assets/observability/observability.mdmarkdown7.4 KB
assets/pom/dependencies.xmlconfig236 B
assets/pom/managed-dependencies.xmlconfig355 B
assets/pom/modules-dependencies.xmlconfig269 B
assets/pom/observability-dependencies.xmlconfig833 B
assets/pom/plugins.xmlconfig2.2 KB
assets/pom/properties.xmlconfig642 B
assets/pom/rules-dependencies.xmlconfig268 B
assets/project/.claude/hooks/guard.shscript7.2 KB
assets/project/.claude/hooks/verify-on-stop.shscript11.9 KB
assets/project/.claude/settings.jsonconfig1.4 KB
assets/project/.codex/hooks.jsonconfig858 B
assets/project/.github/harness/check-file-size.shscript3.7 KB
assets/project/.github/harness/check-protected.shscript10.0 KB
assets/project/.github/workflows/harness-integrity.ymlconfig1.6 KB
assets/project/.github/workflows/verify.ymlconfig440 B
assets/project/.mvn/jvm.configother644 B
assets/project/AGENTS.mdmarkdown10.2 KB
assets/project/CLAUDE.mdmarkdown11 B
assets/project/REVIEW.mdmarkdown2.6 KB
assets/tests/BuildSetupTests.javaother19.6 KB
assets/tests/CodeRulesTests.javaother42.2 KB
assets/tests/ConfigurationKeysTests.javaother14.2 KB
assets/tests/ModuleBoundariesTests.javaother10.3 KB
assets/tests/UnusedCodeTests.javaother9.3 KB
assets/tests/archunit.propertiesother106 B
references/browser-verification.mdmarkdown18.1 KB
references/gates.mdmarkdown7.7 KB
scripts/apply_harness.pyscript59.6 KB
scripts/baseline.pyscript8.9 KB
scripts/report.pyscript6.1 KB

assets/observability/observability.md

View on GitHub
# Observability

The app sends traces, metrics and logs over OTLP to whatever endpoint it is given. It knows nothing about Grafana, ECS or EKS, so moving platforms changes where the collector runs, not the app or the dashboards.

Export is off unless `OTLP_EXPORT_ENABLED=true`.

## The contract

These variables are the whole interface. They are the same on a laptop, ECS and EKS.

| Variable | Default | Meaning |
| --- | --- | --- |
| `OTLP_EXPORT_ENABLED` | `false` | Sends traces, metrics and logs |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | `http://localhost:4318` | Base URL of the collector, with no path |
| `TRACING_SAMPLE_RATE` | `0.1` | Share of requests traced |
| `DEPLOYMENT_ENVIRONMENT` | `local` | Label on all telemetry, and the dashboard's Environment filter |

The settings are in `src/main/resources/application-observability-defaults.yml`, which the main config file imports. Its values win over that file. To change one, set the variable, or set the key in a profile file such as `application-prod.yml`.

## Run it locally

```bash
docker compose -f compose.observability.yml up -d
{{RUN_WITH_PROFILE}}
```

Add the profile to any you already use. Then open <http://localhost:3000>, Dashboards, Project: Service health for requests and logs, JVM and resources for the process. The stack listens on this machine only. Metrics arrive every 10 seconds and rates need two samples, so panels take about 30 seconds to fill. The stack loses its data when the container is removed.

## Check a change

Each dashboard panel is a query, so developers and coding agents ask the same questions. To see the query behind a panel, read it in `observability/dashboards/`.

```bash
# Prometheus: p95 latency for one route
curl -G localhost:9090/api/v1/query --data-urlencode \
  'query=histogram_quantile(0.95, sum by (le) (rate(http_server_requests_milliseconds_bucket{uri="/api/orders"}[5m])))'

# Tempo: failed requests, then one trace with its spans and SQL
curl -G localhost:3200/api/search --data-urlencode 'q={ span.outcome = "SERVER_ERROR" }'
curl localhost:3200/api/traces/<traceId>

# Loki: ERROR lines in the last hour
curl -G localhost:3100/loki/api/v1/query_range --data-urlencode 'query={service_name="{{PROJECT_NAME}}"} | detected_level="error"' --data-urlencode since=1h

# Loki: every log line from one request
curl -G localhost:3100/loki/api/v1/query_range --data-urlencode 'query={service_name="{{PROJECT_NAME}}"} | trace_id="<traceId>"' --data-urlencode since=1h
```

A page that looks right can hide a failure behind it, so read the errors as well as the response.

To check a change, follow one request you sent. Older data can't prove anything about it, and a passing test doesn't show the running app did it. Do this for any change to runtime behaviour:

```bash
python3 observability/check_request.py --service {{PROJECT_NAME}} http://localhost:8080/api/orders
python3 observability/check_request.py --service {{PROJECT_NAME}} --expect 404 http://localhost:8080/api/orders/0
python3 observability/check_request.py --service {{PROJECT_NAME}} -X POST -H 'Content-Type: application/json' -d '{}' <url>
```

It sends the request with a fresh trace id, waits for that trace, and reports the status, spans and ERROR lines. It fails on a 5xx, on a failed span, on an ERROR line, and when no trace arrives. No trace usually means another process answered on that port, or the app runs without the `observability` profile. With `--expect`, failed spans are reported but don't fail the check, because a refused request marks its security span as failed. ERROR lines still fail it unless the expected status is a 5xx. Exit 2 means the app or the stack is down, so nothing was proved.

A request that needs a signed-in session can't be sent this way. Set the header in the browser test that sends it, then read the result with `--trace`:

```text
traceparent: 00-<32 hex trace id>-<16 hex span id>-01
python3 observability/check_request.py --service {{PROJECT_NAME}} --trace <trace id>
```

The check proves the request ran here and hid no failure. It doesn't know what the change was meant to do, so say what in the trace or response shows it worked.

After adding a panel, or upgrading Boot or the image, run this while traffic is flowing. An unknown metric gives an empty panel and no error, and a missing histogram gives `NaN`. It proves the pipeline and the queries work. It doesn't prove a change behaved: it passes while errors exist, and on data left by an app that has stopped. The Slow or failed requests panel may be empty on a healthy service, so the script checks separately that traces arrive.

```bash
python3 observability/check_dashboards.py --service <spring.application.name>
```

## Sensitive data

- `include-parameter-values` is `false`, so spans hold SQL with `?` placeholders. Never turn it on.
- Don't build SQL by joining strings: the values would reach `jdbc.query[n]` span attributes.
- Span `http.url` holds raw paths, so keep personal data out of URLs.
- Only INFO and above is exported, whatever level a profile sets, because framework DEBUG lines can hold sign-in tokens. The console and log file still get DEBUG.
- Log lines, exception messages and `addKeyValue` pairs are exported as they are, so keep personal data out of them.
- A deployed collector and its stores need the same access rules and retention as the logs.
- Only Boot's own `@Async` executor carries the trace id. A pool you build yourself needs `ContextPropagatingTaskDecorator`, or its log lines have none.
- `LogLeakCheck` fails a test when app code logs an email address or a credential, but it only sees tested paths. As a second line, add the collector's `redaction` or `transform` processor before any export. Hashing doesn't protect values that are easy to guess, such as numeric ids.

<!-- failure-filter:begin -->
## Failed requests

`HandledFailureFilter` logs every 5xx that an `@ExceptionHandler` answered, including `Callable` and `DeferredResult` failures, with its stack trace, and records the error on the observation. Without it Spring treats those requests as dealt with. Find them in Tempo with `{ span.outcome = "SERVER_ERROR" }`, not `{ status = error }`: in testing, a 500 answered by a handler left the span status unset. New traces can take up to a minute to appear in search. Handlers return a generic `ProblemDetail` and leave the exception out of the response. The filter only sees handlers that write the response body: one that returns an error view isn't covered, so it must log the exception itself.

<!-- failure-filter:end -->
## Move to ECS

1. Add a collector container to the task. It shares the task's network, so the default endpoint already fits.
2. Set `OTLP_EXPORT_ENABLED=true` and `DEPLOYMENT_ENVIRONMENT=<env>`.
3. Give the task role what the collector's exporters need. The app needs nothing.

## Move to EKS

1. Run the collector as a DaemonSet, or a Deployment with a Service.
2. Set the same variables, with `OTEL_EXPORTER_OTLP_ENDPOINT=http://<collector-service>.<namespace>:4318`.
3. Use `/actuator/health/liveness` and `/actuator/health/readiness` for probes.

## On any deployed platform

CloudWatch and X-Ray OTLP endpoints take SigV4 or a bearer token. This harness sends through a collector so that the app holds no cloud credentials; direct export is possible, but you'd have to add that authentication yourself. After the first deployment, run `check_dashboards.py` with `--prometheus`, `--tempo`, `--loki` and `--environment`, because a collector can rename metrics.
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall