receiver/httpcheck: add structured validation result metrics

.chloggen/httpcheck-validation-result-metric.yaml

@@ -0,0 +1,36 @@
+# Use this changelog template to create an entry for release notes.
+
+# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
+change_type: enhancement
+
+# The name of the component, or a single word describing the area of concern, (e.g. receiver/filelog)
+component: receiver/http_check
+
+# A brief description of the change.  Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: Add structured validation result metrics with per-validation attributes for response validation monitoring.
+
+# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
+issues: [44662]
+
+# (Optional) One or more lines of additional information to render under the primary note.
+# These lines will be padded with 2 spaces and then inserted directly into the document.
+# Use pipe (|) for multiline entries.
+subtext: |
+  Introduces `httpcheck.validation.result`, which emits one datapoint per validation rule with structured attributes including:
+  - `validation.type`
+  - `validation.path`
+  - `validation.expected`
+  - `validation.result`
+
+  This allows users to identify exactly which validation rule passed or failed when multiple validations are configured for a single endpoint.
+
+  Legacy metrics (`httpcheck.validation.passed` and `httpcheck.validation.failed`) continue to work unchanged for backward compatibility.
+
+# If your change doesn't affect end users or the exported elements of any package,
+# you should instead start your pull request title with [chore] or use the "Skip Changelog" label.
+# Optional: The change log or logs in which this entry should be included.
+# e.g. '[user]' or '[user, api]'
+# Include 'user' if the change is relevant to end users.
+# Include 'api' if there is a change to a library API.
+# Default: '[user]'
+change_logs: [user]

receiver/httpcheckreceiver/README.md

@@ -19,7 +19,7 @@ The HTTP Check Receiver can be used for synthetic checks against HTTP endpoints.
 <!-- end autogenerated section -->
 
 This receiver will make a request to the specified `endpoint` using the
-configured `method`. This scraper generates a metric with a label for each HTTP response status class with a value of `1` if the status code matches the
+configured `method`. This scraper generates a metric with an attribute for each HTTP response status class with a value of `1` if the status code matches the
 class. For example, the following metrics will be generated if the endpoint returned a `200`:
 
 ```
@@ -105,6 +105,10 @@ For API monitoring and health checks, response validation metrics are available:
 receivers:
   http_check:
     metrics:
+      # New recommended metric with structured attributes
+      httpcheck.validation.result:
+        enabled: true
+      # Legacy metrics (optional, for backward compatibility)
       httpcheck.validation.passed:
         enabled: true
       httpcheck.validation.failed:
@@ -113,7 +117,97 @@ receivers:
         enabled: true
 ```
 
-These metrics track validation results with `validation.type` attribute indicating the validation type (contains, json_path, size, regex).
+**Recommended:** Use `httpcheck.validation.result` for new deployments as it provides structured attributes for better querying.
+
+**Legacy Metrics** (`httpcheck.validation.passed` / `httpcheck.validation.failed`):
+- Aggregate validation counts by validation type only
+- Do NOT include per-validation attributes such as `validation.expression` or `validation.expected`
+- Maintained for backward compatibility - existing dashboards/alerts will continue to work unchanged
+
+**New Structured Metric** (`httpcheck.validation.result`):
+- Emits one data point per validation rule
+- Provides detailed attributes for precise monitoring:
+
+| Attribute | Description | Example Values |
+|-----------|-------------|----------------|
+| `validation.type` | Type of validation performed | `json_path`, `contains`, `regex`, `size`, `not_contains` |
+| `validation.expression` | The validation expression being evaluated | `system_1`, `healthy`, `^ok$`, `max_size` |
+| `validation.expected` | Expected value (when `equals` specified) | `true`, `ok`, `200` |
+| `validation.result` | Pass/fail result of the validation | `passed`, `failed` |
+
+**Example Output:**
+
+```text
+httpcheck.validation.result{
+  validation.type="json_path",
+  validation.expression="system_1",
+  validation.expected="true",
+  validation.result="passed"
+} = 1
+
+httpcheck.validation.result{
+  validation.type="json_path",
+  validation.expression="system_3",
+  validation.expected="true",
+  validation.result="failed"
+} = 1
+```
+
+This allows you to:
+- Query specific validation paths: `httpcheck.validation.result{validation.expression="system_1"}`
+- Filter by expected value: `httpcheck.validation.result{validation.expected="true"}`
+- Monitor specific validation types: `httpcheck.validation.result{validation.type="json_path", validation.result="failed"}`
+
+### Example: Multiple JSON Path Validations
+
+Given the following API response:
+
+```json
+{
+  "system_1": true,
+  "system_2": true,
+  "system_3": false
+}
+```
+
+And the following validations:
+
+```yaml
+validations:
+  - json_path: "system_1"
+    equals: "true"
+  - json_path: "system_2"
+    equals: "true"
+  - json_path: "system_3"
+    equals: "true"
+```
+
+The receiver emits:
+
+```text
+httpcheck.validation.result{
+  validation.type="json_path",
+  validation.expression="system_1",
+  validation.expected="true",
+  validation.result="passed"
+} = 1
+
+httpcheck.validation.result{
+  validation.type="json_path",
+  validation.expression="system_2",
+  validation.expected="true",
+  validation.result="passed"
+} = 1
+
+httpcheck.validation.result{
+  validation.type="json_path",
+  validation.expression="system_3",
+  validation.expected="true",
+  validation.result="failed"
+} = 1
+```
+
+This allows you to immediately identify that `system_3` failed, without any additional parsing or aggregation.
 
 ### Request Body Support
 
@@ -161,17 +255,17 @@ receivers:
           # String matching
           - contains: "healthy"
           - not_contains: "error"
-          
+
           # JSON path validation using gjson syntax
-          - json_path: "$.status"
+          - json_path: "status"
             equals: "ok"
-          - json_path: "$.services[*].status"
+          - json_path: "services.*.status"
             equals: "up"
-          
+
           # Response size validation (bytes)
           - max_size: 1024
           - min_size: 10
-          
+
           # Regex validation
           - regex: "^HTTP/[0-9.]+ 200"
 ```
@@ -182,7 +276,6 @@ receivers:
 - `max_size` / `min_size`: Response body size limits
 - `regex`: Regular expression matching
 
-
 ### Example Configuration
 
 ```yaml
@@ -203,6 +296,10 @@ receivers:
         enabled: true
       httpcheck.tls.cert_remaining:
         enabled: true
+      # New recommended metric
+      httpcheck.validation.result:
+        enabled: true
+      # Legacy metrics (optional)
       httpcheck.validation.passed:
         enabled: true
       httpcheck.validation.failed:
@@ -230,7 +327,7 @@ receivers:
         endpoint: "https://api.example.com/health"
         validations:
           - contains: "healthy"
-          - json_path: "$.status"
+          - json_path: "status"
             equals: "ok"
           - max_size: 1024
 exporters:

receiver/httpcheckreceiver/documentation.md

@@ -199,3 +199,21 @@ Number of response validations that passed.
 | ---- | ----------- | ------ | ----------------- | ------------------- |
 | http.url | Full HTTP request URL. | Any Str | Recommended | - |
 | validation.type | Type of validation performed (contains, json_path, size, regex) | Any Str | Recommended | - |
+
+### httpcheck.validation.result
+
+Result of a response validation (1 for each validation, with result attribute).
+
+| Unit | Metric Type | Value Type | Aggregation Temporality | Monotonic | Stability |
+| ---- | ----------- | ---------- | ----------------------- | --------- | --------- |
+| {validation} | Sum | Int | Cumulative | false | Development |
+
+#### Attributes
+
+| Name | Description | Values | Requirement Level | Semantic Convention |
+| ---- | ----------- | ------ | ----------------- | ------------------- |
+| http.url | Full HTTP request URL. | Any Str | Recommended | - |
+| validation.type | Type of validation performed (contains, json_path, size, regex) | Any Str | Recommended | - |
+| validation.expression | The validation expression being evaluated (JSONPath, contains string, regex pattern, size constraint). | Any Str | Recommended | - |
+| validation.expected | The expected value for the validation (when equals is specified). | Any Str | Recommended | - |
+| validation.result | The result of the validation (passed or failed). | Any Str | Recommended | - |