Mode d’emploi
- Copiez la commande et examinez le paquet avant de l’installer dans votre environnement agent.
- Consultez le document original pour les outils, identifiants et environnements requis.
- Décrivez les entrées et le livrable souhaité ; comparez la sortie aux sources.
npx skills add https://github.com/talayash/spring-fleet --skill spring-fleet-logging-setupAvant de commencer
- L’installation n’inclut ni abonnement au modèle, ni quota API, ni accès aux fichiers.
- Étoiles et installations reflètent l’activité, pas un test indépendant de qualité ou de sécurité.
Rendu depuis le dépôt source en conservant titres, exemples, code, tableaux, liens et images.
Fleet Logging Setup (logback convention)
Cross-service log correlation needs two things: every service writing to one known directory, and trace keys (trace_id, span_id, sessionId, …) present in each line. This skill installs a logback convention that guarantees both. It is idempotent and opt-in per service.
What trace keys to use (2026)
- Primary: OpenTelemetry / Micrometer Observation. Add the
spring-boot-starter-actuator + micrometer-tracing-bridge-otel (or, on Spring Boot 4, the dedicated spring-boot-starter-opentelemetry). The W3C traceparent header is auto-propagated across HTTP/gRPC, and the Observation API automatically populates MDC keys trace_id (32-char hex) and span_id (16-char hex). These are the modern, framework-default keys.
- Fallback / legacy: sessionId, requestId. Keep them in the pattern for
fleets that pre-date the Observation API or that propagate an application- level session id (auth, X-Request-Id) the user wants to correlate on.
When to use
/debugreports missing log files, or logs only go to the IDE console.- Logs exist but lack a trace key, so correlation falls back to timestamps.
Procedure
- Read the config for
logDirandtraceKeys.
- Start from the template:
${CLAUDE_PLUGIN_ROOT}/logback/logback-spring.xml.
For each service you want covered, place it at <service-repo>/src/main/resources/logback-spring.xml (or merge its appender
- pattern into the existing one), then customize three things:
SERVICE_NAME→ the service'snamefrom the config (used as the log file
base name, so /debug can find it).
- The
%X{...}keys inFLEET_PATTERN→ one per entry intraceKeys. SPRING_FLEET_LOG_DIR→ the configlogDir, or set that env var when
launching the service.
- Ensure the trace keys are in MDC. A pattern can only print
%X{trace_id}
if something put trace_id into the MDC.
- trace_id / span_id: come for free once Micrometer Tracing or the OTel
starter is on the classpath; Spring Boot wires the Observation API which populates MDC automatically. Verify by hitting any endpoint and tailing the log; the keys should already be there.
- sessionId / requestId (legacy): usually require a filter/interceptor
that reads the incoming header (or generates the id), calls MDC.put(...), and clears it in a finally. If propagation across services is missing, the same id must be forwarded as a header on outbound proxy-lib calls. (Modern fleets should rely on W3C traceparent instead and treat sessionId as a business id, not a correlation id.)
- Verify. Run the service, exercise one request, then:
python "${CLAUDE_PLUGIN_ROOT}/scripts/tail_logs.py" \
--config ./spring-fleet.config.json --service <name> --lines 20Confirm lines land in <logDir>/<service>.log and carry the trace key.
Notes
- Keep the same pattern across services so timestamps sort cleanly when
merged. The template's yyyy-MM-dd HH:mm:ss.SSS prefix is what the correlator parses.
- The template also keeps a
CONSOLEappender, so IDE output is unchanged. - For services you will not modify, prefer the (future)
/runtee approach
instead of editing their logback config.
Outside Claude Code
${CLAUDE_PLUGIN_ROOT}is the spring-fleet plugin root. Claude Code fills it in; in Codex it is the folder two directories above this SKILL.md.