feat(skills): Improving Observability support

skills-generator/src/main/resources/skill-indexes/180-skill.xml → skills-generator/src/main/resources/skill-indexes/181-skill.xml

@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <prompt xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:noNamespaceSchemaLocation="https://jabrena.github.io/pml/schemas/0.7.0/pml.xsd"
-      id="180-java-observability-logging">
+      id="181-java-observability-logging">
   <metadata>
     <author>Juan Antonio Breña Moral</author>
     <version>0.15.0-SNAPSHOT</version>
@@ -52,7 +52,7 @@ Implement effective Java logging following standardized frameworks, meaningful l
     </step>
     <step number="2">
       <step-title>Read logging reference and assess current observability</step-title>
-      <step-content>Read `references/180-java-observability-logging.md` and evaluate framework usage, log levels, sensitive-data handling, and config gaps.</step-content>
+      <step-content>Read `references/181-java-observability-logging.md` and evaluate framework usage, log levels, sensitive-data handling, and config gaps.</step-content>
     </step>
     <step number="3">
       <step-title>Apply logging and observability improvements</step-title>

skills-generator/src/main/resources/skill-indexes/182-skill.xml

@@ -0,0 +1,66 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<prompt xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+      xsi:noNamespaceSchemaLocation="https://jabrena.github.io/pml/schemas/0.7.0/pml.xsd"
+      id="182-java-observability-metrics-micrometer">
+  <metadata>
+    <author>Juan Antonio Breña Moral</author>
+    <version>0.15.0-SNAPSHOT</version>
+    <license>Apache-2.0</license>
+    <description>Use when you need to implement or improve Java metrics observability with Micrometer — including meter design, naming/tag conventions, cardinality control, timers/counters/gauges/distribution summaries, percentiles/histograms, Actuator/Prometheus integration, and metrics validation through tests. This should trigger for requests such as Improve metrics; Apply Micrometer; Add metrics observability; Refactor Micrometer instrumentation.</description>
+  </metadata>
+
+  <title>Java Metrics Observability with Micrometer</title>
+  <goal><![CDATA[
+Implement effective Java metrics instrumentation with Micrometer by defining meaningful service-level metrics, controlling cardinality, selecting the right meter type, and exposing production-ready telemetry for dashboards and alerting.
+
+**What is covered in this Skill?**
+
+- Metrics-first observability with Micrometer in Java applications
+- Meter selection: Counter, Timer, DistributionSummary, Gauge, LongTaskTimer
+- Naming and tagging conventions with low-cardinality dimensions
+- Cardinality and meter lifecycle safeguards to prevent time-series explosion
+- Histogram/percentile strategy and SLO-oriented metrics design
+- Integration guidance for Actuator + Prometheus/OpenTelemetry pipelines
+- Testing and verification of metrics registration and values
+
+**Scope:** Application-level metrics design and instrumentation quality for Java services, with emphasis on operationally useful and cost-efficient telemetry.
+]]></goal>
+
+  <constraints>
+    <constraints-description>Metrics instrumentation must be operationally safe, low-cardinality, and validated. Poor tag design or excessive meter creation can degrade observability systems and increase costs.</constraints-description>
+    <constraint-list>
+      <constraint>**LOW CARDINALITY FIRST**: Never tag metrics with unbounded values (userId, UUID, raw URL, full exception message)</constraint>
+      <constraint>**RIGHT METER TYPE**: Use Counter for monotonically increasing events, Timer for latency, Gauge for point-in-time state, and DistributionSummary for sampled values</constraint>
+      <constraint>**BEFORE APPLYING**: Read the reference for good/bad instrumentation examples and anti-patterns</constraint>
+      <constraint>**VERIFY**: Run `./mvnw clean verify` or `mvn clean verify` after changes</constraint>
+    </constraint-list>
+  </constraints>
+
+  <triggers>
+    <trigger-list>
+        <trigger>Improve metrics</trigger>
+        <trigger>Apply Micrometer</trigger>
+        <trigger>Add metrics observability</trigger>
+        <trigger>Refactor Micrometer instrumentation</trigger>
+    </trigger-list>
+  </triggers>
+
+  <steps>
+    <step number="1">
+      <step-title>Define measurement goals and meter contract</step-title>
+      <step-content>Identify key service indicators (throughput, latency, error ratio, saturation) and map each to stable metric names, units, and low-cardinality tags.</step-content>
+    </step>
+    <step number="2">
+      <step-title>Select meter types and instrument code paths</step-title>
+      <step-content>Apply Counter/Timer/Gauge/DistributionSummary/LongTaskTimer where appropriate, ensuring consistent naming conventions and reusable tags.</step-content>
+    </step>
+    <step number="3">
+      <step-title>Harden instrumentation for production</step-title>
+      <step-content>Control cardinality, avoid dynamic meter churn, configure histogram/percentile strategy only where needed, and align export settings with the telemetry backend.</step-content>
+    </step>
+    <step number="4">
+      <step-title>Validate and operationalize metrics</step-title>
+      <step-content>Verify metrics in tests and runtime endpoints, confirm expected labels/units, and ensure dashboards/alerts can consume the emitted series.</step-content>
+    </step>
+  </steps>
+</prompt>

skills-generator/src/main/resources/skill-indexes/183-skill.xml

@@ -0,0 +1,67 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<prompt xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+      xsi:noNamespaceSchemaLocation="https://jabrena.github.io/pml/schemas/0.7.0/pml.xsd"
+      id="183-observability-tracing-opentelemetry">
+  <metadata>
+    <author>Juan Antonio Breña Moral</author>
+    <version>0.15.0-SNAPSHOT</version>
+    <license>Apache-2.0</license>
+    <description>Use when you need to implement or improve distributed tracing with OpenTelemetry in Java — including trace/span modeling, context propagation, semantic conventions, span attributes/events/status, sampling strategy, baggage usage, privacy safeguards, and backend integration with OTLP collectors. This should trigger for requests such as Improve tracing; Apply OpenTelemetry tracing; Add distributed tracing; Refactor tracing instrumentation.</description>
+  </metadata>
+
+  <title>Java Distributed Tracing with OpenTelemetry</title>
+  <goal><![CDATA[
+Implement robust distributed tracing in Java with OpenTelemetry by modeling meaningful spans, preserving context propagation, and instrumenting critical business and infrastructure paths with low-overhead, privacy-safe telemetry.
+
+**What is covered in this Skill?**
+
+- OpenTelemetry tracing fundamentals for Java services
+- Span design: boundaries, parent/child relationships, and operation naming
+- Context propagation across HTTP, messaging, async tasks, and thread boundaries
+- Semantic conventions and stable attribute naming
+- Error/status/event recording best practices
+- Sampling strategy and performance/cost trade-offs
+- Privacy and security controls for trace attributes
+- Testing and verification of trace propagation and span correctness
+
+**Scope:** Distributed tracing quality in application and integration layers, focused on diagnosability, consistency, and operational safety.
+]]></goal>
+
+  <constraints>
+    <constraints-description>Tracing instrumentation must preserve context correctly and avoid leaking sensitive data. Over-instrumentation and high-cardinality attributes can harm cost and signal quality.</constraints-description>
+    <constraint-list>
+      <constraint>**PROPAGATION FIRST**: Ensure context propagation across all sync/async boundaries before adding extra span detail</constraint>
+      <constraint>**NO SENSITIVE DATA**: Never store secrets, credentials, tokens, raw payloads, or PII in span attributes/events</constraint>
+      <constraint>**LOW CARDINALITY ATTRIBUTES**: Avoid unbounded values in attributes that are used for aggregation/search</constraint>
+      <constraint>**VERIFY**: Run `./mvnw clean verify` or `mvn clean verify` after applying tracing changes</constraint>
+    </constraint-list>
+  </constraints>
+
+  <triggers>
+    <trigger-list>
+        <trigger>Improve tracing</trigger>
+        <trigger>Apply OpenTelemetry tracing</trigger>
+        <trigger>Add distributed tracing</trigger>
+        <trigger>Refactor tracing instrumentation</trigger>
+    </trigger-list>
+  </triggers>
+
+  <steps>
+    <step number="1">
+      <step-title>Define trace model and critical flows</step-title>
+      <step-content>Identify high-value request and async flows, define operation boundaries, and choose span names/attributes aligned with semantic conventions.</step-content>
+    </step>
+    <step number="2">
+      <step-title>Instrument and propagate context</step-title>
+      <step-content>Add OpenTelemetry spans to key boundaries and ensure trace context is propagated across HTTP clients/servers, messaging, and executor-based async work.</step-content>
+    </step>
+    <step number="3">
+      <step-title>Harden span data and sampling</step-title>
+      <step-content>Record status/errors/events consistently, remove sensitive data, control attribute cardinality, and configure sampling/exporters according to environment needs.</step-content>
+    </step>
+    <step number="4">
+      <step-title>Validate traces end-to-end</step-title>
+      <step-content>Verify parent-child relationships, propagation continuity, and backend visibility through tests and runtime checks.</step-content>
+    </step>
+  </steps>
+</prompt>