Configuration de l'échantillonnage APM
L'échantillonnage APM est une configuration facultative permettant à l'agent Java APM et au traceur APM de surveiller une fraction des étendues en fonction de la règle d'échantillonnage.
L'échantillonnage APM est une implémentation d'échantillonnage basée sur une étendue racine qui permet aux traces échantillonnées d'obtenir une représentation de toutes les traces. La décision d'échantillonnage est prise en fonction de règles d'échantillonnage. Lorsque la décision d'échantillonner une étendue racine (ou trace) est prise, toutes ses étendues enfant sont également échantillonnées. Si une étendue racine n'est pas échantillonnée, les étendues enfant ne le sont pas non plus.
Règles disponibles
Les règles suivantes sont disponibles pour l'échantillonnage APM :
| Règle | Nom de règle | Paramètre de règle | Exemple de paramètre | Description |
|---|---|---|---|---|
| Constante | constant | nombre entier
(0 ou supérieur) |
50 | Echantillonnage constant à l'intervalle défini par la valeur de paramètre.
Par exemple, si le paramètre est défini sur 50, la première trace de chaque groupe de 50 traces est échantillonnée. Si le paramètre est défini sur 0, aucune trace n'est échantillonnée. Si le paramètre est défini sur 1, toutes les traces sont échantillonnées. |
| Probabiliste | probabilistic | nombre décimal compris entre 0 et 1 | 0,2 | Echantillonnage déterminé par la probabilité indiquée.
Par exemple, si le paramètre est défini sur 0,2, chaque trace a 20 % de chance d'être échantillonnée. |
| Taux limité | limited-rate | <limite>/<secondes> | 500/60 | Echantillonnage jusqu'à la limite spécifiée pour chaque fenêtre de secondes spécifiée.
Par exemple, si le paramètre est défini sur 500/60, les 500 premières traces sont échantillonnées toutes les 60 secondes. |
| Taux limité par opération | per-operation-rate | <limite>/<secondes> | 10/60 | Echantillonnage jusqu'à la limite spécifiée pour chaque fenêtre de secondes spécifiée par nom d'opération.
Par exemple, si le paramètre est défini sur 10/60, les 10 premières traces de chaque nom d'opération sont échantillonnées toutes les 60 secondes. |
| Nom d'opération | operation | <op1>,<op2>, ...<opN> | /status_order,/status_ship | Echantillonnage du nom d'opération indiqué uniquement. Vous pouvez indiquer plusieurs opérations en les séparant par une virgule. |
| Nom d'opération dans une expression régulière | operation-regex | <expression régulière> | /status_(order|ship) | Echantillonnage des étendues dont le nom d'opération correspond à l'expression régulière uniquement. |
Méthodes de configuration
- Propriétés à une seule règle : moyen simple de définir une règle applicable à toutes les traces.
- Fichier de configuration : moyen complet de définir des échantillonnages, notamment des règles de branchement et de priorité des opérations.
Si les deux méthodes sont configurées, les propriétés à une seule règle sont prioritaires sur le fichier de configuration. La méthode des propriétés à une seule règle est alors utilisée.
Il n'existe aucune configuration d'échantillonnage par défaut. Si aucune propriété à une seule règle ni aucun fichier de configuration n'a été spécifié, toutes les nouvelles traces démarrées par l'agent APM ou le traceur APM sont échantillonnées.
Propriétés à une seule règle
Les propriétés à une seule règle permettent de définir et d'appliquer facilement une même règle d'échantillonnage à toutes les traces.
Les propriétés disponibles sont les suivantes :
| Type et description de propriété | Pris en charge par | Propriétés | Exemple |
|---|---|---|---|
|
AgentConfig.properties Mettez à jour le fichier |
Agent APM |
|
|
|
Générateur de traceurs Mettez à jour le générateur de traceurs. |
Traceur APM |
|
|
|
Propriétés système Mettez à jour les propriétés système. |
Agent APM et traceur APM |
|
|
|
Variables d'environnement Mettez à jour les variables d'environnement. |
Agent APM et traceur APM |
|
Pour Windows :
Pour Linux :
|
Priorité des propriétés : si plusieurs propriétés sont définies, l'ordre de priorité, de la priorité la plus élevée à la plus faible, est le suivant : propriétés système, variables d'environnement et AgentConfig.properties.
Fichier de configuration
Le fichier de configuration permet de spécifier les fonctionnalités d'échantillonnage de tous les services dans un seul fichier présentant les caractéristiques suivantes :
- Le fichier de configuration est au format ACML (un sous-ensemble de YAML) et doit être spécifié dans
Sampling.acml. - Plusieurs configurations d'échantillonnage pour différents services peuvent être définies et partagées à partir d'un seul fichier de configuration.
- Vous pouvez définir plusieurs règles d'échantillonnage. Les règles d'échantillonnage peuvent être reliées à d'autres règles par le biais de branches pour former une arborescence de règles. Chaque évaluation de règle peut déboucher sur 2 résultats : True ou False. True signifie que la trace est échantillonnée. False signifie qu'elle ne l'est pas. Dans une règle avec branche, le résultat de la feuille finale est utilisé en tant que décision d'échantillonnage.
- Les règles portant des noms spécifiques peuvent être hiérarchisées avec leur propre règle d'échantillonnage.
Pour le traceur APM, il n'existe aucun emplacement de configuration par défaut. Le fichier de configuration d'échantillonnage doit être spécifié dans une propriété de traceur, une propriété système ou une variable d'environnement à l'aide de la propriété com.oracle.apm.agent.sampling.file. La valeur de la propriété correspond au chemin complet du fichier de configuration d'échantillonnage.
La propriété com.oracle.apm.agent.sampling.file s'applique uniquement au traceur APM. Pour l'agent APM, cette propriété n'est pas requise. Vous devez simplement placer le fichier d'échantillonnage Sampling.acml dans le répertoire oracle-apm-agent/config/<version>.
| Type et description de propriété | Pris en charge par | Propriété | Exemple |
|---|---|---|---|
| Générateur de traceurs
Mettez à jour le générateur de traceurs. |
Traceur APM | com.oracle.apm.agent.sampling.file |
|
| Propriété système Mettez à jour les propriétés système. |
Agent APM et traceur APM | com.oracle.apm.agent.sampling.file |
-Dcom.oracle.apm.agent.sampling.file=/home/user/apm/config/Sampling.acml |
| Variable d'environnement
Mettez à jour la variable d'environnement. |
Agent APM et traceur APM | com_oracle_apm_agent_sampling_file |
Pour Windows :
Pour Linux :
|
La valeur de la propriété com.oracle.apm.agent.sampling.file correspond au chemin complet du fichier de configuration d'échantillonnage. Lorsque vous spécifiez le fichier de configuration d'échantillonnage, nous vous recommandons d'utiliser le nom Sampling.acml, mais vous pouvez utiliser n'importe quel autre nom de votre choix.
- Echantillonnage : cette stratégie utilise l'entrée
samplinget définit une arborescence de règles pour l'évaluation de la trace. - Priorité des opérations : cette stratégie utilise l'entrée
operation_priority. Lorsqu'elle est définie, elle remplace l'échantillonnage si le nom d'opération de l'étendue racine de la trace correspond au nom défini. Chaque nom d'opération défini possède sa propre arborescence de règles de décision.
Décision de pré-échantillonnage
La décision de pré-échantillonnage est une fonction d'échantillonnage qui permet à l'échantillonneur de prendre une décision en fonction de l'étendue parent avant d'appliquer la règle d'échantillonnage.
Exemple :
sampling_config:
-
service:
- s1
- s2
pre_sampling_decision:
ignore: rum
sampling:
rule: constant
param: 1000
true:
rule: per-operation-rate
param: 1000/60Pour plus de détails sur la syntaxe pre_sampling_decision, reportez-vous à la section Sampling.acml File Format.
Format du fichier Sampling.acml
Le format du fichier Sampling.acml est le suivant :
| Sampling.acml | Description |
|---|---|
|
|
Noeud représentant un tableau des diverses configurations d'échantillonnage. |
|
|_ |
Elément de tableau d'une configuration d'échantillonnage. |
|
|____ |
Noeud des noms des services auxquels cette configuration d'échantillonnage est appliquée. |
|
|_______ |
Elément de tableau de noms de service. |
|
|____ |
(Facultatif) Noeud de décision de pré-échantillonnage.
La décision est évaluée dans l'ordre de remplacement → appliquer → ignorer. Dans le cas où une source est définie dans plusieurs décisions, la première décision ayant la source correspondante est utilisée. Lorsqu'aucun type parent ne correspond à une décision, l'agent APM suit l'indicateur d'étendue parent échantillonné pour l'étendue locale. S'il n'y avait pas d'étendue parent, la règle d'échantillonnage est évaluée pour l'étendue locale. Tous les noeuds de décision sont facultatifs. Si aucune décision de pré-échantillonnage n'est nécessaire, |
|
|_______ |
Exemple d'intervalle d'agent APM local, quel que soit l'indicateur échantillonné parent de la source indiquée. Si l'étendue parent n'est pas échantillonnée, une nouvelle trace est démarrée avec l'étendue locale en tant que racine. Pour les valeurs |
|
|_______ |
Forcer la réévaluation de l'échantillonnage quel que soit l'indicateur échantillonné parent de la source indiquée. Si l'étendue parent n'est pas échantillonnée et que l'étendue locale de l'agent APM est évaluée pour échantillonner, une nouvelle trace est démarrée. Si l'étendue parent est échantillonnée et que l'étendue locale de l'agent APM est évaluée comme échantillonnée, l'étendue locale de l'agent APM continue sur la trace de l'étendue parent. Pour les valeurs |
|
|_______ |
Ignorer l'échantillonnage de l'étendue d'agent APM local du parent spécifié. Pour les valeurs |
|
|____ |
Noeud de l'échantillonnage de base.
Facultatif si le noeud |
|
|_______ |
Arborescence de règles d'échantillonnage de cette configuration. |
|
|____ |
Tableau des noms d'opération avec des règles remplaçant la règle d'échantillonnage de base. |
|
|_______ |
Nom devant correspondre au nom d'opération de l'étendue racine de la trace. |
|
|_______ |
Règle à appliquer en cas de correspondance. |
|
|_______ |
Expression régulière devant correspondre au nom d'opération de l'étendue racine de la trace. |
|
|_______ |
Règle à appliquer en cas de correspondance. |
-
Si le noeud de service (
service:) n'est pas spécifié, la configuration d'échantillonnage est appliquée à tous les services sans configuration d'échantillonnage dédiée. Si plusieurs configurations présentent le même nom de service, seule la dernière configuration avec ce nom est utilisée.Si un fichier contient à la fois des configurations avec le noeud de service et sans celui-ci, la configuration dont le nom de service correspond au nom de service de l'agent APM ou du traceur APM est prioritaire.
-
Si les noeuds d'échantillonnage (
sampling:) et de priorité des opérations (operation_priority:) sont tous les deux spécifiés, la priorité est donnée à operation_priority. Si le nom de l'étendue racine de la trace correspond au nom d'opération du noeud operation_priority, le noeud est évalué avec la règle associée au nom d'opération. Si le nom de l'étendue racine de la trace ne correspond à aucun nom d'opération du noeud operation_priority, le noeud d'échantillonnage est évalué. -
Si le noeud d'échantillonnage (
sampling:) n'est pas spécifié ou si aucune règle n'est spécifiée, la trace n'est pas échantillonnée lorsque aucune règle operation_priority n'est applicable. -
Si le noeud de priorité des opérations (
operation_priority:) est spécifié et que le nom d'opération de l'étendue racine de la trace correspond à n'importe quel nom d'opération operation_priority, la règle du nom correspondant est utilisée pour l'évaluation à la place de la règle d'échantillonnage de base.
Noeud de règle
Le noeud de règle du fichier Sampling.acml se présente au format suivant :
| Noeud <règle> | Description |
|---|---|
rule: <rule_name> |
Nom de la règle d'échantillonnage. |
param: <rule_parameter> |
Paramètre de la règle. |
true: |
Résultat True de l'évaluation de la règle. La valeur peut être une autre règle (<règle >) ou vide.
Si ce noeud n'est pas spécifié ou si sa valeur est vide, l'évaluation True est également le résultat final de l'évaluation de l'échantillonnage et la trace est échantillonnée. |
|___<rule> |
Noeud <règle> de branche en cas d'évaluation True. |
false: |
Résultat False de l'évaluation de la règle. La valeur peut être une autre règle (<règle >) ou vide.
Si ce noeud n'est pas spécifié ou si sa valeur est vide, l'évaluation False est également le résultat final de l'évaluation et la trace n'est pas échantillonnée. |
|___<rule> |
Noeud <règle> de branche en cas d'évaluation False. |
L'apport de modifications au fichier de configuration d'échantillonnage Sampling.acml ne requiert pas le redémarrage de l'agent APM.
Valeur source
Si vous utilisez pre_sampling_decision, vous pouvez fournir les informations source.
La valeur <source> du fichier Sampling.acml peut être vide ou contenir plusieurs sources. Pour connaître les valeurs prises en charge, reportez-vous au tableau ci-dessous.
| Nom de la source | Description |
|---|---|
| apm | Source de l'agent APM. |
| rhum | Source de la métrique de valorisation (Real User Monitoring).
Il ne s'agit pas d'un agent APM et toujours de l'étendue parent de l'agent Java. |
| synthétique | Source synthétique.
Par défaut, toutes les demandes de synthèse sont échantillonnées. |
| * | Toutes les sources. |
| ? | Tout type de source non défini dans <source>. |
| NULL | Tout parent sans source identifiable. |
Exemples de fichier Sampling.acml
- Règle applicable à tous les services
sampling_config: - sampling: # Every trace has 2% chance to be sampled. rule: probabilistic param: 0.02 - Echantillonnage probabiliste avec un nombre minimal
sampling_config: - sampling: # For every 60 seconds duration, 5 root spans of each operation name are sampled, # followed by 10% chance of sampling. rule: per-operation-rate param: 5/60 true: false: rule: probabilistic param: 0.1 - Echantillonnage des opérations spécifiées uniquement
sampling_config: - service: - order_dept - shipping_dept operation_priority: # For /order operation trace root span, 1 of every 10 traces is sampled. - name: "/order" rule: constant param: 10 # For /ship operation trace root span, 1 of every 50 traces is sampled. - name: "/ship" rule: constant param: 50 # For /status_order or /status_ship operations, there is a 50% sampling chance. - regex: "/status_(order|ship)" rule: probabilistic param: 0.5 - Autre exemple d'échantillonnage
sampling_config: - # With service node, this config is only applied to service s1 and s2. service: - s1 - s2 sampling: # 5 root span of any operation name are sampled every 60 seconds. Starting from # the 6th span of an operation name, there is a 20% chance the span is sampled. rule: per-operation-rate param: 5/60 false: rule: probabilistic param: 0.2 operation_priority: # For /order operation, 1 of every 10 spans is sampled. - name: "/order" rule: constant param: 10 # For /ship operation, first 3 are sampled per 60 seconds and then 10% chance after - name: "/ship" rule: limited-rate param: 3/60 false: rule: probabilistic param: 0.01 - # With service node, this config is only applied to service s3 and s4. service: - s3 - s4 sampling: # There is a 5% chance any trace is sampled. rule: probabilistic param: 0.05 - # Without service node, this config is applied to any service except s1, s2, s3 and s4. sampling: # There is a 10% chance any trace is sampled. rule: probabilistic param: 0.1
Désactivation de l'échantillonnage
L'échantillonnage est activé implicitement lorsque des propriétés à une seule règle ou le fichier de configuration sont spécifiés. Il peut ensuite être explicitement désactivé à l'aide de la propriété suivante :
| Type de propriété | Pris en charge par | Propriété | Exemple |
|---|---|---|---|
| AgentConfig.properties | Agent APM | com.oracle.apm.agent.sampling.enabled |
com.oracle.apm.agent.sampling.enabled=false |
| Générateur de traceurs | Traceur APM | com.oracle.apm.agent.sampling.enabled |
|
| Propriété système | Agent APM et traceur APM | com.oracle.apm.agent.sampling.enabled |
-Dcom.oracle.apm.agent.sampling.enabled=false |
| Variable d'environnement | Agent APM et traceur APM | com_oracle_apm_agent_sampling_enabled |
Pour Windows :
Pour Linux :
|
Balise d'étendue
Si des propriétés de règle d'échantillonnage ou un fichier de configuration sont spécifiés et que l'échantillonnage n'est pas désactivé, chaque étendue racine de trace échantillonnée comporte une balise SamplingEvaluation du flux d'évaluation.
rule: per-operation-rate
param: 5/60
false:
rule: probabilistic
param: 0.2Valeur de la balise SamplingEvaluation
Voici des exemples de valeur de la balise SamplingEvaluation de l'étendue racine échantillonnée :
Valeur de la balise SamplingEvaluation
|
Description |
|---|---|
| per-operation-rate(5/60):true | Les 5 premières traces échantillonnées toutes les 60 secondes. |
| per-operation-rate(5/60):false->probabilistic(0.2):true | Les 20 % de traces échantillonnées après les 5 traces échantillonnées toutes les 60 secondes. |