CRITIQUE : TOUS les chemins de script sont relatifs au dossier de cette skill. Exécutez-les avec le chemin complet (par exemple, scripts/metrics-query).

Interrogation de métriques Axiom

Interrogez les métriques OpenTelemetry stockées dans MetricsDB d'Axiom.

Configuration

Exécutez scripts/setup pour vérifier les exigences (curl, jq, ~/.axiom.toml).

Configuration dans ~/.axiom.toml (partagée avec axiom-sre) :

[deployments.prod]
url = "https://api.axiom.co"
token = "xaat-your-token"
org_id = "your-org-id"

Le dataset cible doit être de type otel:metrics:v1.

Découverte des datasets

Listez tous les datasets dans un déploiement :

scripts/datasets <deployment>

Filtrez pour afficher uniquement les datasets de métriques :

scripts/datasets <deployment> --kind otel:metrics:v1

Cela retourne le name, edgeDeployment et kind de chaque dataset. Utilisez le nom du dataset dans les appels ultérieurs à metrics-info et metrics-query.

Résolution du déploiement edge

Les datasets peuvent résider dans différents déploiements edge (par exemple, us-east-1 vs eu-central-1). Les scripts résolvent automatiquement l'URL edge régionale correcte avant d'interroger. Aucune configuration manuelle n'est nécessaire — metrics-info et metrics-query détectent le déploiement edge du dataset et acheminent les requêtes vers le bon endpoint.

Si la résolution échoue ou le déploiement edge est inconnu, les requêtes reviennent à l'URL de déploiement dans ~/.axiom.toml.

Apprentissage de la syntaxe des requêtes de métriques

CRITIQUE : Vous DEVEZ exécuter metrics-spec avant de composer votre première requête dans une session. NE DEVINEZ JAMAIS la syntaxe MPL — elle change au fil du temps et la spécification est la seule source de vérité.

scripts/metrics-spec <deployment> <dataset>

Consultez à nouveau la spécification lors de l'utilisation d'un opérateur inconnu, quand une requête retourne une erreur de syntaxe, ou lors de la construction de requêtes histogram/multi-métriques.

Flux de travail

1. Listez les datasets : Exécutez scripts/datasets <deployment> pour voir les datasets disponibles et leurs déploiements edge
2. Récupérez la spec : Exécutez scripts/metrics-spec <deployment> <dataset> — cette étape est obligatoire avant d'écrire une requête
3. Découvrez les métriques : Listez les métriques disponibles via scripts/metrics-info <deployment> <dataset> metrics
4. Explorez les tags : Listez les tags et valeurs de tags pour comprendre les options de filtrage. Si le listing des métriques échoue, utilisez les tags et valeurs de tags pour identifier les entités pertinentes, puis utilisez-les pour lister les métriques pour des tags spécifiques.
5. Écrivez et exécutez la requête : Composez une requête de métriques et exécutez-la via scripts/metrics-query
6. Itérez : Affinez les filtres, agrégations et groupements en fonction des résultats

Si l'utilisateur fournit un service, hôte ou nom d'entité spécifique à rechercher, utilisez find-metrics pour localiser les métriques correspondantes :

scripts/metrics-info <deployment> <dataset> find-metrics "frontend"

N'utilisez PAS find-metrics comme étape de découverte générale — elle nécessite une valeur de recherche connue.

Interrogation des métriques

Exécutez une requête de métriques sur un dataset :

scripts/metrics-query <deployment> '<mpl>' '<startTime>' '<endTime>'

Exemples :

# Requête simple
scripts/metrics-query prod \
  '`my-dataset`:`http.server.duration` | align to 5m using avg' \
  '2025-06-01T00:00:00Z' \
  '2025-06-02T00:00:00Z'

# Requête avec filtrage (notez les backticks sur les noms de tags avec points)
scripts/metrics-query prod \
  '`my-dataset`:`http.server.duration` | where `service.name` == "frontend" and method == "GET" | align to 5m using avg | group by status_code using sum' \
  'now-1d' \
  'now'

Découverte (endpoints Info)

Utilisez scripts/metrics-info pour explorer quelles métriques, tags et valeurs existent dans un dataset avant d'écrire des requêtes. La plage horaire par défaut est les dernières 24 heures ; remplacez-la avec --start et --end.

Lister les métriques dans un dataset

scripts/metrics-info <deployment> <dataset> metrics

Lister les tags dans un dataset

scripts/metrics-info <deployment> <dataset> tags

Lister les valeurs pour un tag spécifique

scripts/metrics-info <deployment> <dataset> tags <tag> values

Lister les tags pour une métrique spécifique

scripts/metrics-info <deployment> <dataset> metrics <metric> tags

Lister les valeurs de tags pour une métrique et un tag spécifiques

scripts/metrics-info <deployment> <dataset> metrics <metric> tags <tag> values

Trouver les métriques correspondant à une valeur de tag

scripts/metrics-info <deployment> <dataset> find-metrics "<search-value>"

Plage horaire personnalisée

Toutes les commandes info acceptent --start et --end pour des plages horaires personnalisées :

scripts/metrics-info prod my-dataset metrics \
  --start 2025-06-01T00:00:00Z \
  --end 2025-06-02T00:00:00Z

Gestion des erreurs

Les erreurs HTTP retournent du JSON avec les champs message, code et optionnellement detail :

{"message": "description", "code": 400, "detail": {"errorType": 1, "message": "raw error"}}

Codes de statut courants :

• 400 — Syntaxe de requête invalide ou nom de dataset incorrect
• 401 — Authentification manquante ou invalide
• 403 — Pas de permission pour interroger/ingérer ce dataset
• 404 — Dataset non trouvé
• 429 — Limitation du débit dépassée
• 500 — Erreur interne du serveur

En cas d'erreur 500, réexécutez l'appel de script défaillant avec les drapeaux curl -v pour capturer les en-têtes de réponse, puis signalez la valeur de l'en-tête traceparent ou x-axiom-trace-id à l'utilisateur. Cet ID de trace est essentiel pour déboguer l'échec avec l'équipe backend.

Scripts

Exécutez n'importe quel script sans arguments pour voir l'utilisation complète.