Configurer l'échantillonnage APM

L'échantillonnage APM est une configuration facultative pour l'agent Java APM et le traceur APM afin de surveiller une fraction des intervalles en fonction de la règle d'échantillonnage.

L'échantillonnage APM est un échantillonnage basé sur un intervalle racine, qui permet aux traces échantillonnées de produire la représentation de toutes les traces. La décision d'échantillonnage est prise en fonction de règles d'échantillonnage. Lorsqu'il est décidé d'échantillonner un intervalle racine (identique à la trace), celui-ci et tous les intervalles enfants sont échantillonnés. Lorsqu'un intervalle racine n'est pas échantillonné, les intervalles enfants ne sont pas échantillonnés.

Cette section couvre les sujets suivants :

Règles disponibles

Les règles suivantes sont disponibles pour l'échantillonnage APM :

Règle	Nom de la règle	Paramètre de la règle	Exemple de paramètre	Description
Constante	constant	entier (0 ou plus)	50	Échantillonner continuellement une fois par valeur de paramètre spécifiée. Par exemple, si le paramètre est réglé à 50, la première des 50 traces est échantillonnée. Si la valeur du paramètre est 0, aucune trace n'est échantillonnée. Si le paramètre est réglé à 1, chaque trace est échantillonnée.
Probabiliste	probabilistic	nombre décimal compris entre 0 et 1	0,2	Échantillon déterminé selon la probabilité spécifiée. Par exemple, si le paramètre est réglé à 0,2, les probabilités qu'une trace soit échantillonnée sont de 20 %.
Taux limité	limited-rate	<limite>/<secondes>	500/60	Échantillonner jusqu'à la limite spécifiée pour chaque fenêtre de secondes spécifiée. Par exemple, si le paramètre est réglé à 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	Échantillonner 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 réglé à 10/60, les 10 premières traces de chaque nom d'opération sont échantillonnées toutes les 60 secondes.
Nom de l'opération	operation	<op1>,<op2>, ...<opN>	/status_order,/status_ship	Échantillonner uniquement l'opération dont le nom est spécifié. Plusieurs opérations peuvent indiquées en les séparant par une virgule.
Nom de l'opération dans l'expression rationnelle	operation-regex	<regex>	/status_(order\|ship)	Échantillonner uniquement les intervalles dont l'opération correspond à l'expression rationnelle.

Méthodes de configuration

Les méthodes suivantes sont disponibles pour configurer l'échantillonnage APM :

Propriétés de règle unique : Un moyen facile de définir une règle applicable à toutes les traces.
Fichier de configuration : Méthode complète de définition des échantillonnages, y compris des règles de branchement et des règles de priorité des opérations.

Si les deux méthodes sont configurées, les propriétés de règle unique ont préséance sur le fichier de configuration. Par conséquent, c'est la méthode des propriétés de règle unique qui est utilisée.

Il n'existe aucune configuration d'échantillonnage par défaut. Si aucune propriété de règle unique ou aucun fichier de configuration n'a été spécifié, toutes les nouvelles traces lancées par l'agent APM ou le traceur APM sont échantillonnées.

Propriétés de règle unique

Les propriétés de règle unique permettent de définir et d'appliquer facilement une règle d'échantillonnage à toutes les traces.

Les propriétés suivantes sont disponibles :

Type et description des propriétés	Pris en charge par	Propriétés	Exemple
AgentConfig.properties Mettre à jour le fichier `AgentConfig.properties` situé dans le répertoire `oracle-apm-agent/config/<version>`.	Agent APM	`com.oracle.apm.agent.sampling.rule com.oracle.apm.agent.sampling.param`	`com.oracle.apm.agent.sampling.rule=limited-rate com.oracle.apm.agent.sampling.param=1000/60`
Générateur de traceur Mettre à jour le générateur de traceur.	Traceur APM	`com.oracle.apm.agent.sampling.rule com.oracle.apm.agent.sampling.param`	`new ApmTracer.Builder(...) ... .withProperty(com.oracle.apm.agent.sampling.rule, "limited-rate") .withProperty(com.oracle.apm.agent.sampling.param, "1000/60") ... .build();`
Propriétés de système Mettre à jour les propriétés du système.	Agent APM et traceur APM	`com.oracle.apm.agent.sampling.rule com.oracle.apm.agent.sampling.param`	`java -Dcom.oracle.apm.agent.sampling.rule=limited-rate -Dcom.oracle.apm.agent.sampling.param=1000/60 -javaagent:... <main_class>`
Variables d'environnement Mettre à jour les variables d'environnement.	Agent APM et traceur APM	`com_oracle_apm_agent_sampling_rule com_oracle_apm_agent_sampling_param`	Pour Windows : `set com_oracle_apm_agent_sampling_rule=limited-rate set com_oracle_apm_agent_sampling_param=1000/60` Pour Linux : `export com_oracle_apm_agent_sampling_rule=limited-rate export com_oracle_apm_agent_sampling_param=1000/60`

Priorité des propriétés : Si plusieurs propriétés sont définies, l'ordre de priorité de la plus élevée à la plus faible est le suivant : Propriétés du système, Variables d'environnement et AgentConfig.properties.

Fichier de configuration

Le fichier de configuration permet de spécifier toutes les fonctions d'échantillonnage pour tous les services dans un seul fichier présentant les caractéristiques suivantes :

Le fichier de configuration est au format ACML (sous-ensemble de YAML) à spécifier dans Sampling.acml.
Plusieurs configurations d'échantillonnage pour des services différents peuvent être définies et partagées à partir d'un seul fichier de configuration.
La règle d'échantillonnage n'est pas limitée à une seule. Des règles d'échantillonnage peuvent comporter des branchements à d'autres règles et ainsi former un arbre de règles. Chaque évaluation de règle a 2 résultats : vrai ou faux. Vrai signifie que la trace est échantillonnée, dans le cas contraire le résultat est Faux. Dans une règle à branchement, le résultat de la feuille terminale est utilisé pour la décision d'échantillonnage.
Les règles portant des noms précis peuvent être priorisées au moyen de leur propre règle d'échantillonnage.

Pour le traceur APM, il n'y a pas d'emplacement de configuration par défaut. Le fichier de configuration de l'échantillonnage doit être spécifié avec la propriété de traceur, la propriété de système ou la variable d'environnement à l'aide de la propriété com.oracle.apm.agent.sampling.file. La valeur de la propriété est le chemin complet du fichier de configuration de l'échantillonnage.

La propriété com.oracle.apm.agent.sampling.file s'applique uniquement au traceur APM. Pour l'agent APM, la propriété n'est pas nécessaire. Il suffit de placer le fichier d'échantillonnage Sampling.acml dans le répertoire oracle-apm-agent/config/<version>.

Type et description des propriétés Pris en charge par Propriété Exemple

Type et description des propriétés	Pris en charge par	Propriété	Exemple
Générateur de traceur Mettre à jour le générateur de traceur.	Traceur APM	`com.oracle.apm.agent.sampling.file`	`new ApmTracer.Builder(...) ... .withProperty(com.oracle.apm.agent.sampling.file, "/home/user/apm/config/Sampling.acml") ... .build();`
Propriété de système Mettre à jour les propriétés du 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 Mettre à jour la variable d'environnement.	Agent APM et traceur APM	`com_oracle_apm_agent_sampling_file`	Pour Windows : `set com_oracle_apm_agent_sampling_file=c:\apm\config\Sampling.acml` Pour Linux : `export com_oracle_apm_agent_sampling_file=/home/user/apm/config/Sampling.acml`

Générateur de traceur

Mettre à jour le générateur de traceur.

Traceur APM

com.oracle.apm.agent.sampling.file

new ApmTracer.Builder(...)
    ...
    .withProperty(com.oracle.apm.agent.sampling.file, "/home/user/apm/config/Sampling.acml")
    ...
    .build();

Propriété de système

Mettre à jour les propriétés du 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

Mettre à jour la variable d'environnement.

Agent APM et traceur APM

com_oracle_apm_agent_sampling_file

Pour Windows :

set com_oracle_apm_agent_sampling_file=c:\apm\config\Sampling.acml

Pour Linux :

export com_oracle_apm_agent_sampling_file=/home/user/apm/config/Sampling.acml

La valeur de la propriété com.oracle.apm.agent.sampling.file est le chemin complet du fichier de configuration de l'échantillonnage. Lorsqu'un fichier de configuration d'échantillonnage est spécifié, le nom recommandé est Sampling.acml, mais vous pouvez utiliser n'importe quel autre nom privilégié.

Il existe 2 stratégies d'échantillonnage :

Échantillonnage : Cette stratégie utilise l'entrée sampling et définit un arbre de règles pour l'évaluation des traces.
Priorité de l'opération : Cette stratégie utilise l'entrée operation_priority et, lorsqu'elle est définie, elle remplace l'échantillonnage si le nom de l'opération sur l'intervalle racine de la trace correspond au nom défini. Chaque nom d'opération défini possède son propre arbre 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 basée sur l'intervalle 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/60

Pour plus de détails sur la syntaxe pre_sampling_decision, voir Format de fichier échantillonnage.acml.

Format du fichier Sampling.acml

Le format du fichier Sampling.acml est le suivant :

Sampling.acml	Description
`sampling_config:`	Noeud représentant un tableau de différentes configurations d'échantillonnage.
\|_`-`	Élément de tableau de configurations d'échantillonnage.
\|____`service:`	Noeud des noms de service auxquels cette configuration d'échantillonnage est appliquée.
\|_______`- <service-name>`	Élément de tableau de noms de service.
\|____`pre_sampling_decision:`	Noeud de décision de pré-échantillonnage (facultatif). La décision est évaluée dans l'ordre de remplacement → imposer → 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 de parent ne correspond à une décision, l'agent APM suit l'indicateur d'intervalle parent échantillonné pour l'intervalle local. S'il n'y avait pas d'intervalle parent, la règle d'échantillonnage est évaluée pour l'intervalle local. Tous les noeuds de décision sont facultatifs. Si aucune décision de pré-échantillonnage n'est nécessaire, `pre_sampling_decision` ne doit pas être défini.
\|_______`override: <source>`	Exemple d'intervalle d'agent APM local, peu importe l'indicateur échantillonné parent de la source spécifiée. Si l'intervalle parent n'est pas échantillonné, une nouvelle trace est lancée avec l'intervalle local en tant que racine. Pour les valeurs `source`, voir Valeurs sources.
\|_______`enforce: <source>`	Forcer l'échantillonnage de réévaluation, quel que soit l'indicateur échantillonné parent de la source spécifiée. Si l'intervalle parent n'est pas échantillonné et que l'intervalle d'agent APM local est évalué pour être échantillonné, une nouvelle trace est démarrée. Si l'intervalle parent est échantillonné et que l'intervalle d'agent APM local est évalué pour être échantillonné, l'intervalle d'agent APM local se poursuit sur la trace de l'intervalle parent. Pour les valeurs `source`, voir Valeurs sources.
\|_______`ignore: <source>`	Ignorer l'échantillonnage de l'intervalle d'agent APM local du parent spécifié. Pour les valeurs `source`, voir Valeurs sources.
\|____`sampling:`	Noeud d'échantillonnage de base. Il est facultatif si le noeud `operation_priority` est utilisé.
\|_______`<rule>`	Arbre de règles d'échantillonnage de cette configuration.
\|____`operation_priority:`	Tableau des noms d'opération avec les règles qui remplacent la règle d'échantillonnage de base.
\|_______`- name: <operation-name>`	Nom correspondant au nom de l'opération sur l'intervalle racine de trace.
\|_______`<rule>`	Règle à appliquer s'il y a correspondance.
\|_______`- regex: <operation-name-regex>`	Expression rationnelle devant correspondre au nom de l'opération sur l'intervalle racine de trace.
\|_______`<rule>`	Règle à appliquer s'il y a 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. Lorsque plusieurs configurations ont le même nom de service, seule la dernière configuration comportant ce nom de service est utilisée.

Si un fichier contient des configurations avec et sans ce noeud de service, la configuration avec le nom de service correspondant à l'agent APM ou au nom de service du traceur APM est prioritaire.
Lorsque les noeuds d'échantillonnage (sampling:) et operation_priority (operation_priority:) sont tous deux spécifiés, le noeud operation_priority a priorité. Si le nom de l'intervalle racine de trace correspond au nom de l'opération du noeud operation_priority, il est évalué avec la règle associée au nom de l'opération. Si le nom de l'intervalle racine de la trace ne correspond à aucun nom d'opération du noeud operation_priority, le noeud d'échantillonnage est évalué.
If sampling node (sampling:) is not specified, or no rule is specified, then the trace is not sampled when no operation_priority rule is applicable.
Lorsque le noeud operation_priority (operation_priority:) est spécifié, si le nom d'opération de l'intervalle racine de la trace correspond à un nom d'opération operation_priority, la règle du nom correspondant est utilisée pour l'évaluation au lieu de la règle d'échantillonnage de base.

Noeud de règle

Le noeud de règle provenant du fichier Sampling.acml a le format suivant :

Noeud <rule>	Description
`rule: <rule_name>`	Nom de la règle d'échantillonnage.
`param: <rule_parameter>`	Paramètre de la règle.
`true:`	Résultat Vrai de l'évaluation de la règle. La valeur peut être une autre règle <rule> ou vide. Si ce noeud n'est pas spécifié ou que la valeur du noeud est vide, l'évaluation Vrai est également le résultat final de l'évaluation de l'échantillonnage, et la trace est échantillonnée.
`\|___<rule>`	Noeud de branche <rule> sur une évaluation Vrai.
`false:`	Résultat Faux de l'évaluation de la règle. La valeur peut être une autre règle <rule> ou vide. Si ce noeud n'est pas spécifié ou que la valeur du noeud est vide, l'évaluation Faux est également le résultat final de l'évaluation et la trace n'est pas échantillonnée.
`\|___<rule>`	Noeud de branche <rule> sur une évaluation Faux.

Note

Les modifications apportées au fichier de configuration d'échantillonnage Sampling.acml ne nécessitent pas de redémarrer l'agent APM.

Valeur source

Si vous utilisez pre_sampling_decision, vous avez la possibilité de fournir les informations sources.

La valeur <source> du fichier Sampling.acml peut être vide ou contenir plusieurs sources. Pour les valeurs prises en charge, voir le tableau ci-dessous.

Nom de la source	Description
API	Source de l'agent APM.
rhum	Source RUM (Real User Monitoring). Il ne s'agit pas de l'intervalle d'agent APM et toujours de l'intervalle parent de l'agent Java.
synthétique	Source synthétique. Par défaut, toutes les demandes synthétiques sont échantillonnées.
*	Toute source.
?	Tout type de source non défini dans <source>.
nul	Tout parent sans source identifiable.

Exemples de fichier Sampling.acml

Règle qui s'applique à tous les services

sampling_config:
  -
     sampling:
       # Every trace has 2% chance to be sampled.
       rule: probabilistic
       param: 0.02

Probabiliste avec 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

Échantillonner seulement les opérations indiquées

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ésactiver l'échantillonnage

L'échantillonnage est activé implicitement lorsque des propriétés de règle unique ou le fichier de configuration sont spécifiés. Il peut ensuite être désactivé explicitement à l'aide de la propriété suivante :

Type de propriétés	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 traceur	Traceur APM	`com.oracle.apm.agent.sampling.enabled`	`new ApmTracer.Builder(...) ... .withProperty(com.oracle.apm.agent.sampling.enabled, "false") ... .build();`
Propriété de 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 : `set com_oracle_apm_agent_sampling_enabled=false` Pour Linux : `export com_oracle_apm_agent_sampling_enabled=false`

Marqueur d'intervalle

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 intervalle racine de trace échantillonné comporte un marqueur SamplingEvaluation du flux d'évaluation.

Voir ci-dessous un exemple d'arbre de règles utilisé aux fins d'évaluation :

rule: per-operation-rate
param: 5/60
false:
     rule: probabilistic
     param: 0.2

Valeur du marqueur SamplingEvaluation

Voir ci-dessous la valeur du marqueur SamplingEvaluation de l'intervalle racine échantillonné :

Valeur du marqueur `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 5 traces échantillonnées toutes les 60 secondes.

Documentation sur Oracle Cloud Infrastructure

Configurer l'échantillonnage APM