Simple Agility Telemetry Adoption

This page holds the work instructions for each product team to bring its product onto the telemetry contract. It covers two decisions in the decision log:

• SA-6: products log in Elastic Common Schema (ECS) JSON, with trace.id as the correlation identifier.
• SA-5: product instances are named <product>-<env>, and the plane attaches that name as a label.

The contract states the rule; this page states what each repository has to change. When an item is finished:

1. Tick it here, with the date and the commit.
2. Update the matching row on SimpleAgilityRoadmap phase 1.

If an instruction turns out to be wrong for your codebase, fix this page rather than working around it. The next team will hit the same thing.

Status

Team	Repository	State (2026-10-12)
jakemon	~/source/jakemon	Done. It attaches service and service_instance to product metrics and logs. Live instances: wiki-prod, crafter-prod, roller-prod (logs only), wiki-dev and crafter-dev.
Wikantik	~/source/jspwiki	Not started. Its logs are already ECS JSON. It needs service.name, ECS context keys, trace.id, and an updated conformance script.
Roller	~/source/roller	Not started. It logs plain text and has no /metrics.
CrafterCMS	third-party	No work. jakemon labels it; its log format is not ours to change.

Coordination rules for every team

• Never emit a label named instance, service or service_instance on /metrics, and never put those names in log lines as labels. The plane owns them.
• jakemon recognises your containers by name. Production Wikantik is repo-* on docker1, and production Roller is roller-* on docker2. If you rename a compose project or a container, tell jakemon before you deploy, or your logs lose their service_instance.
• A new metrics endpoint is reached through jakemon. Tell jakemon the host, port and path, and jakemon adds the scrape in that host's apps.alloy.
• Never make trace.id, transaction.id or any other per-request value a Loki label. See the contract, §2.

Wikantik (~/source/jspwiki)

Wikantik already uses log4j2's ECS layout. LogQL's | json and Loki's detected_level work on its lines today, so these items close the remaining gaps.

• W1. Name the service. In docker/config/log4j2-docker.xml, change the EventTemplateAdditionalField key from application to service.name. Keep the value wikantik.

• W2. Rename the request filter's context keys to ECS names. These are in wikantik-observability/src/main/java/com/wikantik/observability/RequestCorrelationFilter.java:

  Current key	ECS key
  requestId	transaction.id
  method	http.request.method
  uri	url.path
  remoteAddr	client.ip
  userAgent	user_agent.original

  RequestCorrelationFilterTest reads requestId; update it as well.

• W3. Add trace.id in the same filter.

  • Take the trace-id from an inbound traceparent header.
  • Otherwise, take an inbound X-Correlation-Id.
  • Otherwise, mint a 32-hex-character identifier.

  Put the identifier in the ThreadContext as trace.id, and clear it when the request ends, as the filter already does for its other keys.

• W4. Propagate the identifier. Send traceparent and X-Correlation-Id on every outbound call, including MCP tool calls to other stack members.

• W5. Name events and namespace extra fields.

  • A business or behavioural event line carries event.action (page_view, bundle_assembled).
  • A product-specific field goes under wikantik.*.
  • Never add a new top-level key.

• W6. Update the conformance script (bin/simple-agility-conformance.sh). The other products depend on this.

  • Required log keys become @timestamp, log.level, message and service.name.
  • The informational check looks for trace.id instead of correlation_id.
  • Dotted keys are accepted whether they are written flat ("log.level") or nested ({"log": {"level": …}}).
  • Update the header comment that lists the old envelope keys.

Done when:

• A request sent with a traceparent header can be found with {service_instance="wiki-prod"} | json | trace_id="<that trace-id>" in Loki.
• bin/simple-agility-conformance.sh passes against production.

Roller (~/source/roller)

Coding Agent Execution Blueprint: The complete, code-level execution specification for items R1 through R5 is detailed in RollerTelemetryHandoffSpec. Consult it for exact Maven XML, Log4j2 additivity requirements, TraceCorrelationFilter.java reference implementation, and port 8090 Actuator configuration.

Roller is Spring Boot 4.1 on log4j2, and it already depends on Actuator.

• R1. Log ECS JSON to the console. In app/src/main/resources/log4j2.xml, replace the console appender's PatternLayout with:

  <JsonTemplateLayout eventTemplateUri="classpath:EcsLayout.json">
      <EventTemplateAdditionalField key="service.name" value="roller"/>
  </JsonTemplateLayout>
  

  • Add the org.apache.logging.log4j:log4j-layout-template-json dependency. Its version comes from the existing log4j-bom (2.26.1).
  • The file appenders can stay as they are; the plane reads only stdout.

• R2. Add a request filter that puts trace.id and transaction.id into the log4j ThreadContext.

  • trace.id is resolved in the same order as Wikantik W3.
  • transaction.id is a fresh identifier for each request.
  • Clear both when the request ends.

• R3. Propagate the identifier. Send traceparent and X-Correlation-Id on outbound calls to listmonk, Umami and Keycloak.

• R4. Name events and namespace extra fields. Use event.action for events, put Roller-specific fields under roller.*, and add no new top-level keys.

• R5. Expose metrics and health.

  • Add micrometer-registry-prometheus.
  • Expose the Actuator prometheus and health endpoints.
  • Prefix custom metrics with roller_.
  • Give jakemon the port and path. jakemon then adds the scrape, and roller-prod gains metrics.

Done when:

• {service_instance="roller-prod", container="roller-app-1"} | json | log_level="ERROR" returns parsed lines.
• up{service_instance="roller-prod"} is 1.
• bin/simple-agility-conformance.sh passes. This needs Wikantik's W6 first.

A new product joining the stack

1. Pick a product short name. Record it in SimpleAgilityDecisionLog SA-5.
2. Follow the telemetry contract from the start:
   • ECS JSON on stdout;
   • trace.id propagation;
   • /metrics with your prefix;
   • a liveness endpoint.
3. Add a section to this page and a row to Status.
4. Ask jakemon to register the instance (<product>-<env>) for metrics and logs.

jakemon (done; kept as the reference)

• J1. Product scrape targets carry service and service_instance (2026-10-12, jakemon 6d86140).
• J2. Container log streams carry them through each host's discovery.relabel "products" hook. bin/validate.sh enforces the hook and the <product>-<env> form (2026-10-12, 6d86140).
• J3. service means only the product on the plane. The per-systemd-unit resource series use unit (2026-10-12, 6d86140).
• J4. Add Roller's scrape when R5 lands.

See also

• SimpleAgilityTelemetryContract: the rule these instructions implement
• SimpleAgilityDecisionLog: why ECS, and why these label names
• SimpleAgilityRoadmap: where each item sits in the sequence
• WikantikPlatformHub and RollerHub: the product hubs

---

Cluster Hub: Simple Agility Stack Hub (simple-agility)