Telemetry Attribute Contract Audit

{
  "assumptions": [
    "Cardinality is counted within the batch supplied, and each distinct value of an attribute is one series in a metrics backend, which is why it is reported as a risk.",
    "An attribute that appears as two types across a batch cannot be indexed by a typed backend, whatever any single record looks like."
  ],
  "attributes": [
    {
      "attribute": "environment",
      "declared": true,
      "distinct_count": 1,
      "presence_rate": 0.8,
      "records": 4,
      "types": {
        "string": 4
      }
    },
    {
      "attribute": "latency_ms",
      "declared": true,
      "distinct_count": 4,
      "presence_rate": 0.8,
      "records": 4,
      "types": {
        "integer": 2,
        "number": 1,
        "string": 1
      }
    },
    {
      "attribute": "request_id",
      "declared": false,
      "distinct_count": 4,
      "presence_rate": 0.8,
      "records": 4,
      "types": {
        "string": 4
      }
    }
  ],
  "cardinality_limit": 3,
  "complete": true,
  "conformant": false,
  "distinct_attribute_count": 5,
  "examined_record_count": 5,
  "finding_count": 9,
  "findings": [
    {
      "attribute": "request_id",
      "code": "UNDECLARED_ATTRIBUTE",
      "detail": "Record 0 carries request_id, which the contract does not declare.",
      "record": 0
    },
    {
      "attribute": "request_id",
      "code": "UNDECLARED_ATTRIBUTE",
      "detail": "Record 1 carries request_id, which the contract does not declare.",
      "record": 1
    },
    {
      "attribute": "request_id",
      "code": "UNDECLARED_ATTRIBUTE",
      "detail": "Record 2 carries request_id, which the contract does not declare.",
      "record": 2
    }
  ],
  "findings_by_code": {
    "ATTRIBUTES_MISSING": 1,
    "ATTRIBUTE_CARDINALITY_RISK": 2,
    "ATTRIBUTE_TYPE_INCONSISTENT": 1,
    "ATTRIBUTE_TYPE_MISMATCH": 1,
    "UNDECLARED_ATTRIBUTE": 4
  },
  "limitations": [
    "Attribute shape and cardinality over the batch supplied. Whether the batch represents real traffic is not knowable here, so a cardinality figure is a lower bound.",
    "conformant is true only when every record was examined, every required attribute was present, and no type or cardinality problem was found."
  ],
  "limits": {
    "cardinalityWarning": 100,
    "maxAttributes": 500,
    "maxEvents": 2000,
    "maxFindings": 500,
    "maxPartitions": 500,
    "maxSchemas": 100
  },
  "not_examined": [],
  "observed_at": "2026-10-02T00:00:00.000Z",
  "passed": false,
  "records_without_attributes": 1,
  "request_id": "example-request",
  "service_id": "telemetry_attribute_contract_audit",
  "service_version": "1.0.0",
  "supplied_record_count": 5
}

# bash or zsh: see the payment challenge. Nothing is charged.
curl -sS -g -i -X POST 'https://api.zfinia.com/x402/v1/telemetry-attribute-contract-audit' \
  -H 'content-type: application/json' \
  --data-raw '{"attribute_pointer":"/attributes","cardinality_limit":3,"contract":{"optional":["region"],"required":["service","environment"],"types":{"environment":"string","latency_ms":"number","service":"string"}},"records":[{"attributes":{"environment":"prod","latency_ms":31.2,"region":"ap-southeast-2","request_id":"r-1","service":"checkout"},"name":"http.request"},{"attributes":{"environment":"prod","latency_ms":44,"region":"ap-southeast-2","request_id":"r-2","service":"checkout"},"name":"http.request"},{"attributes":{"environment":"prod","latency_ms":"51","request_id":"r-3","service":"checkout"},"name":"http.request"},{"attributes":{"environment":"prod","latency_ms":28,"request_id":"r-4","service":"checkout"},"name":"http.request"},{"name":"http.request"}]}'

# x402 v2 sends the challenge base64-encoded in the PAYMENT-REQUIRED header (v1 sends it in the body).
# To read the header:
curl -sS -g -o /dev/null -D - -X POST 'https://api.zfinia.com/x402/v1/telemetry-attribute-contract-audit' \
  -H 'content-type: application/json' \
  --data-raw '{"attribute_pointer":"/attributes","cardinality_limit":3,"contract":{"optional":["region"],"required":["service","environment"],"types":{"environment":"string","latency_ms":"number","service":"string"}},"records":[{"attributes":{"environment":"prod","latency_ms":31.2,"region":"ap-southeast-2","request_id":"r-1","service":"checkout"},"name":"http.request"},{"attributes":{"environment":"prod","latency_ms":44,"region":"ap-southeast-2","request_id":"r-2","service":"checkout"},"name":"http.request"},{"attributes":{"environment":"prod","latency_ms":"51","request_id":"r-3","service":"checkout"},"name":"http.request"},{"attributes":{"environment":"prod","latency_ms":28,"request_id":"r-4","service":"checkout"},"name":"http.request"},{"name":"http.request"}]}' \
  | grep -i '^payment-required:' | cut -d' ' -f2 | tr -d '\r' | base64 --decode

// npm i @x402/fetch @x402/evm viem
import { wrapFetchWithPayment, x402Client } from "@x402/fetch";
import { registerExactEvmScheme } from "@x402/evm/exact/client";
import { privateKeyToAccount } from "viem/accounts";

// Pays at most $0.12 per call.
const client = new x402Client().setSpendControls({ maxAmountPerPayment: "$0.12" });
registerExactEvmScheme(client, { signer: privateKeyToAccount(process.env.EVM_PRIVATE_KEY) });
const pay = wrapFetchWithPayment(fetch, client);

// Not sure it's safe to pay? ToolVet checks it first for $0.005. Pay for that from a separate
// client: this one is capped at $0.12 per payment. GET https://toolvet.app/api/v1/check?url=https%3A%2F%2Fapi.zfinia.com%2Fx402%2Fv1%2Ftelemetry-attribute-contract-audit&method=POST
const res = await pay("https://api.zfinia.com/x402/v1/telemetry-attribute-contract-audit", {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({
    "attribute_pointer": "/attributes",
    "cardinality_limit": 3,
    "contract": {
      "optional": [
        "region"
      ],
      "required": [
        "service",
        "environment"
      ],
      "types": {
        "environment": "string",
        "latency_ms": "number",
        "service": "string"
      }
    },
    "records": [
      {
        "attributes": {
          "environment": "prod",
          "latency_ms": 31.2,
          "region": "ap-southeast-2",
          "request_id": "r-1",
          "service": "checkout"
        },
        "name": "http.request"
      },
      {
        "attributes": {
          "environment": "prod",
          "latency_ms": 44,
          "region": "ap-southeast-2",
          "request_id": "r-2",
          "service": "checkout"
        },
        "name": "http.request"
      },
      {
        "attributes": {
          "environment": "prod",
          "latency_ms": "51",
          "request_id": "r-3",
          "service": "checkout"
        },
        "name": "http.request"
      },
      {
        "attributes": {
          "environment": "prod",
          "latency_ms": 28,
          "request_id": "r-4",
          "service": "checkout"
        },
        "name": "http.request"
      },
      {
        "name": "http.request"
      }
    ]
  }),
});
console.log(res.status, await res.text());

# pip install "x402[requests,evm]"
import os
from eth_account import Account
from x402 import x402ClientSync
from x402.http.clients import x402_requests
from x402.mechanisms.evm import EthAccountSigner
from x402.mechanisms.evm.exact.register import register_exact_evm_client

# Pays at most $0.12 per call.
client = x402ClientSync().set_spend_controls({"max_amount_per_payment": "$0.12"})
register_exact_evm_client(client, EthAccountSigner(Account.from_key(os.environ["EVM_PRIVATE_KEY"])))

with x402_requests(client) as session:
    res = session.post(
        "https://api.zfinia.com/x402/v1/telemetry-attribute-contract-audit",
        json={
            "attribute_pointer": "/attributes",
            "cardinality_limit": 3,
            "contract": {
                "optional": [
                    "region",
                ],
                "required": [
                    "service",
                    "environment",
                ],
                "types": {
                    "environment": "string",
                    "latency_ms": "number",
                    "service": "string",
                },
            },
            "records": [
                {
                    "attributes": {
                        "environment": "prod",
                        "latency_ms": 31.2,
                        "region": "ap-southeast-2",
                        "request_id": "r-1",
                        "service": "checkout",
                    },
                    "name": "http.request",
                },
                {
                    "attributes": {
                        "environment": "prod",
                        "latency_ms": 44,
                        "region": "ap-southeast-2",
                        "request_id": "r-2",
                        "service": "checkout",
                    },
                    "name": "http.request",
                },
                {
                    "attributes": {
                        "environment": "prod",
                        "latency_ms": "51",
                        "request_id": "r-3",
                        "service": "checkout",
                    },
                    "name": "http.request",
                },
                {
                    "attributes": {
                        "environment": "prod",
                        "latency_ms": 28,
                        "request_id": "r-4",
                        "service": "checkout",
                    },
                    "name": "http.request",
                },
                {
                    "name": "http.request",
                },
            ],
        },
    )
    print(res.status_code, res.text)