Configuración del muestreo de APM

El muestreo de APM es una configuración opcional para el agente Java de APM y el rastreador de APM para supervisar una fracción de los períodos según la regla de muestreo.

El muestreo de APM es una implementación de muestreo basada en el intervalo raíz que permite a los rastreos muestreados generar la representación de todos los rastreos. La decisión de muestreo se toma en función de las normas de muestreo. Cuando se decide muestrear un período raíz (igual que el rastreo), se muestrean el período raíz y también todos los períodos secundarios. Cuando no se muestrea un período raíz, no se muestrean todos los períodos secundarios.

Reglas disponibles

Las siguientes reglas están disponibles para el muestreo de APM:

Regla Nombre de regla Parámetro de regla Parámetro de muestreo Descripción
Constante constant integer

(0 o superior)

50 Muestrea de forma constante una vez por valor de parámetro especificado.

Por ejemplo, si el parámetro se define en 50, se muestrea el primero de cada 50 rastreos. Si el parámetro está definido en 0, no se muestrea ningún rastreo. Si el parámetro se define en 1, se muestrean todos los rastreos.

Probabilístico probabilistic número decimal entre 0 y 1 0,2 El muestreo se decide según la probabilidad especificada.

Por ejemplo, si el parámetro se define en 0,2, existe una probabilidad del 20 % de que se muestree un rastreo.

Frecuencia limitado limited-rate <limit>/<seconds> 500/60 Muestrea hasta el límite especificado para cada ventana de segundos especificada.

Por ejemplo, si el parámetro se define en 500/60, se muestrean los primeros 500 rastreos cada 60 segundos.

Frecuencia limitada por operación per-operation-rate <limit>/<seconds> 10/60 Muestrea hasta el límite especificado para cada ventana de segundos especificada por nombre de operación.

Por ejemplo, si el parámetro se define en 10/60, se muestrean los primeros 10 rastreos de cada nombre de operación cada 60 segundos.

Nombre de la operación operation <op1>,<op2>, ...<opN> /status_order,/status_ship Muestra solo el nombre de operación especificado. Se pueden especificar varias operaciones delimitadas por una coma.
Nombre de operación en expresión regular operating-regex <regex> /status_(order|ship) Muestrea solo los períodos con la operación que coincide con la expresión regular.

Métodos de configuración

Están disponibles los siguientes métodos para configurar el muestreo de APM:
  • Propiedades de regla única: forma sencilla de definir una regla aplicable a todos los rastreos.
  • Archivo de configuración: forma completa de definir muestreos, incluidas las reglas de bifurcación y las reglas de prioridad de operación.

Si se configuran ambos métodos, las propiedades de regla única tienen prioridad sobre el archivo de configuración; por lo tanto, el método de propiedades de regla única es el que se utiliza.

No hay ninguna configuración de muestreo por defecto. Si no hay ninguna propiedad de regla única o no se ha especificado ningún archivo de configuración, se muestrean todos los rastreos nuevos iniciados por el agente de APM o el rastreador de APM.

Propiedades de regla única

Las propiedades de regla única permiten definir y aplicar una regla de muestreo a todos los rastreos de una forma sencilla.

Están disponibles las siguientes propiedades:

Tipo y descripción de propiedades Soportadas por Propiedades Ejemplo

AgentConfig.properties

Actualice el archivo AgentConfig.properties ubicado en el directorio oracle-apm-agent/config/<version>.

Agente de 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

Creador de rastreador

Actualice el creador de rastreador.

Rastreador de 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();

Propiedades del sistema

Actualiza las propiedades del sistema.

Agente de APM y rastreador de 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 de entorno

Actualiza las variables de entorno.

Agente de APM y rastreador de APM
com_oracle_apm_agent_sampling_rule
com_oracle_apm_agent_sampling_param
Para Windows:
set com_oracle_apm_agent_sampling_rule=limited-rate
set com_oracle_apm_agent_sampling_param=1000/60
Para Linux:
export com_oracle_apm_agent_sampling_rule=limited-rate
export com_oracle_apm_agent_sampling_param=1000/60

Prioridad de las propiedades: si se define más de una propiedad, el orden de prioridad de mayor a menor es el siguiente: Propiedades del sistema, Variables de entorno y AgentConfig.properties.

Archivo de configuración

El archivo de configuración permite especificar todas las funciones de muestreo de todos los servicios en un único archivo con las siguientes características:

  • El archivo de configuración tiene el formato ACML (subjuego de YAML) que se especifique en Sampling.acml.
  • Se pueden definir y compartir varias configuraciones de muestreo para diferentes servicios desde un único archivo de configuración.
  • La regla de muestreo no se limita a una. Las reglas de muestreo se pueden bifurcar en otras reglas para formar un árbol de reglas. Cada evaluación de regla tiene 2 resultados: verdadero o falso. Verdadero significa que el rastreo se ha muestreado; de lo contrario, es falso. En una regla bifurcada, el resultado de hoja terminal se utiliza para la decisión de muestreo.
  • Las reglas con nombres específicos se pueden priorizar con su propia regla de muestreo.

Para el rastreador de APM, no hay ninguna ubicación de configuración por defecto. El archivo de configuración de muestreo se debe especificar con la propiedad de rastreador, la propiedad del sistema o la variable de entorno mediante la propiedad com.oracle.apm.agent.sampling.file. El valor de la propiedad es la ruta completa del archivo de configuración de muestreo.

La propiedad com.oracle.apm.agent.sampling.file solo se aplica al rastreador de APM. Para el agente de APM, la propiedad no es necesaria. Solo tiene que colocar el archivo de muestreo Sampling.acml en el directorio oracle-apm-agent/config/<version>.

Tipo y descripción de propiedades Soportadas por Propiedad Ejemplo
Creador de rastreador

Actualice el creador del rastreador.

Rastreador de APM com.oracle.apm.agent.sampling.file
new ApmTracer.Builder(...)
    ...
    .withProperty(com.oracle.apm.agent.sampling.file, "/home/user/apm/config/Sampling.acml")
    ...
    .build();
Propiedad del sistema

Actualiza las propiedades del sistema.

Agente de APM y rastreador de APM com.oracle.apm.agent.sampling.file -Dcom.oracle.apm.agent.sampling.file=/home/user/apm/config/Sampling.acml
Variable de entorno

Actualiza la variable de entorno.

Agente de APM y rastreador de APM com_oracle_apm_agent_sampling_file

Para Windows:

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

Para Linux:

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

El valor de la propiedad com.oracle.apm.agent.sampling.file es la ruta completa del archivo de configuración de muestreo. Cuando se especifica, el nombre de archivo de configuración de muestreo recomendado es Sampling.acml, pero puede utilizar cualquier otro nombre de su preferencia.

Hay 2 estrategias de muestreo:
  • Muestreo: utiliza la entrada sampling y define un árbol de reglas para la evaluación del rastreo.
  • Prioridad de operación: utiliza la entrada operation_priority y, cuando se define, sustituye el muestreo si el nombre de operación del intervalo raíz de rastreo coincide con el nombre definido. Cada nombre de operación definido tiene su propio árbol de reglas de decisión.

Decisión previa al muestreo

La decisión previa al muestreo es una característica de muestreo que permite al muestreador tomar una decisión basada en el intervalo principal antes de aplicar la regla de muestreo.

Ejemplo:

sampling_config:
    -
        service:
            -   s1
            -   s2
        pre_sampling_decision:
            ignore: rum
        sampling:
            rule: constant
            param: 1000
            true:
                rule: per-operation-rate
                param: 1000/60

Para obtener más información sobre la sintaxis pre_sampling_decision, consulte Sampling.acml File Format.

Formato del archivo Sampling.acml

A continuación se muestra el formato del archivo Sampling.acml:

Sampling.acml Descripción

sampling_config:

Nodo que representa una matriz de configuración de muestreo diferente.

|_-

Elemento de matriz de configuración de muestreo.

|____service:

Nodo de nombres de servicio al que se aplica esta configuración de muestreo.

|_______- <nombre-servicio>

Elemento de matriz de nombre de servicio.

|____pre_sampling_decision:

(Opcional) Nodo de decisión previa al muestreo.

La decisión se evalúa en el orden de anulación → forzar → Ignorar.

En caso de que se defina un origen en más de una decisión, se utilizará la primera decisión que tenga el origen coincidente. Cuando ningún tipo principal coincide con cualquier decisión, APM Agent sigue el indicador de extensión principal muestreado para un período local.

Si no había un período principal, se evalúa la regla de muestreo para el período local.

Todos los nodos de decisión son opcionales. Si no se necesita ninguna decisión previa al muestreo, no se debe definir pre_sampling_decision.

|_______override: <source>

Ampliar ejemplo de agente de APM local independientemente del indicador principal muestreado del origen especificado.

Si no se muestra el intervalo principal, se inicia un nuevo rastreo con el intervalo local como raíz.

Para ver los valores source, consulte Valores de origen.

|_______enforce: <source>

Fuerce la reevaluación del muestreo independientemente del indicador principal muestreado del origen especificado.

Si no se muestra el intervalo principal y se evalúa el intervalo del agente de APM local para su muestreo, se inicia un nuevo rastreo.

Si se muestra el intervalo principal y se evalúa el intervalo del agente de APM local para su muestreo, el intervalo del agente de APM local continúa en el rastreo del intervalo principal.

Para ver los valores source, consulte Valores de origen.

|_______ignore: <source>

Ignore el muestreo del intervalo de agente de APM local del principal especificado.

Para ver los valores source, consulte Valores de origen.

|____sampling:

Nodo de muestreo de base.

Es opcional si se utiliza el nodo operation_priority.

|_______<rule>

Árbol de reglas de muestreo de esta configuración.

|____operation_priority:

Matriz de nombres de operaciones con reglas que sustituyen la regla de muestreo base.

|_______- name: <operation-name>

Nombre para coincidir con nombre de operación del período raíz de rastreo.

|_______<rule>

Regla que se aplicará si hay coincidencia.

|_______- regex: <operation-name-regex>

Expresión regular para coincidir con el nombre de operación del período raíz de rastreo.

|_______<rule>

Regla que se aplicará si hay coincidencia.
  • Si no se especifica el nodo de servicio (service:), la configuración de muestreo se aplica a todos los servicios sin una configuración de muestreo dedicada. Cuando varias configuraciones tienen el mismo nombre de servicio, solo se utiliza la última configuración con ese nombre de servicio.

    Si un archivo tiene configuraciones con y sin este nodo de servicio, se da prioridad a la configuración con el nombre de servicio que coincide con el nombre de servicio de agente de APM o de rastreador de APM.

  • Si se han especificado tanto el nodo sampling (sampling:) como el nodo operation_priority (operation_priority:), se da prioridad a operation_priority. Si el nombre del período raíz de rastreo coincide con el nombre de operación del nodo operation_priority, este se evalúa con la regla asociada al nombre de operación. Si el nombre del período raíz de rastreo no coincide con ningún nombre de operación del nodo operation_priority, se evalúa el nodo sampling.

  • Si no se especifica el nodo de muestreo (sampling:) o no se especifica ninguna regla, el rastreo no se muestra cuando no se aplica ninguna regla operation_priority.

  • Si se ha especificado el nodo operation_priority (operation_priority:), si el nombre de operación del período raíz de rastreo coincide con cualquier nombre de operación de operation_priority, se utiliza la regla de nombre coincidente para la evaluación en lugar de la regla de muestreo base.

Nodo de regla

El nodo de regla del archivo Sampling.acml tiene el siguiente formato:

<rule> node Descripción
rule: <rule_name> Nombre de la regla de muestreo.
param: <rule_parameter> Parámetro de la regla.
true: Resultado verdadero de la evaluación de regla. El valor puede ser otra <rule> o estar vacío.

Si no se ha especificado este nodo o el valor del nodo está vacío, la evaluación de verdadero es también el resultado final de la evaluación del muestreo y se muestrea el rastreo.

|___<rule> Nodo de <rule> de bifurcación en la evaluación de verdadero.
false: Resultado de falso de la evaluación de regla. El valor puede ser otra <regla> o estar vacío.

Si no se ha especificado este nodo o el valor del nodo está vacío, la evaluación de falso es también el resultado final de la evaluación y no se muestrea el rastreo.

|___<rule> Nodo de <rule> de bifurcación en la evaluación de falso.
Nota

Los cambios en el archivo de configuración de muestreo Sampling.acml no necesitan reiniciar el agente de APM.

Valor de origen

Si utiliza pre_sampling_decision, tiene la opción de proporcionar la información de origen.

El valor <source> del archivo Sampling.acml puede estar vacío o puede contener varios orígenes. Para ver los valores soportados, consulte la siguiente tabla.

Nombre de fuente Descripción
Chao Origen del agente de APM.
ron Origen de RUM (Real User Monitoring).

No abarca APM Agent y siempre es el intervalo principal del agente de Java.

sintético Fuente sintética.

Por defecto, se muestrean todas las solicitudes sintéticas.

* Cualquier origen.
? Cualquier tipo de origen no definido en <source>.
nulo Cualquier padre sin fuente identificable.

Ejemplos de archivo Sampling.acml

  1. Regla que se aplica a todos los servicios
    sampling_config:
      -
         sampling:
           # Every trace has 2% chance to be sampled.
           rule: probabilistic
           param: 0.02
  2. Probabilístico con recuento mínimo
    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
  3. Operaciones especificadas solo de muestreo
    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
  4. Otro ejemplo de muestreo
    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

Desactivación del muestreo

El muestreo se activa de forma implícita cuando se especifican propiedades de regla única o el archivo de configuración. Posteriormente, se puede desactivar de forma explícita mediante la siguiente propiedad:

Tipos de propiedades Soportadas por Propiedad Ejemplo
AgentConfig.properties Agente de APM com.oracle.apm.agent.sampling.enabled com.oracle.apm.agent.sampling.enabled=false
Creador de rastreador Rastreador de APM com.oracle.apm.agent.sampling.enabled
new ApmTracer.Builder(...)
    ...
    .withProperty(com.oracle.apm.agent.sampling.enabled, "false")
    ...
    .build();
Propiedad del sistema Agente de APM y rastreador de APM com.oracle.apm.agent.sampling.enabled -Dcom.oracle.apm.agent.sampling.enabled=false
Variable de entorno Agente de APM y rastreador de APM com_oracle_apm_agent_sampling_enabled

Para Windows:

set com_oracle_apm_agent_sampling_enabled=false

Para Linux:

export com_oracle_apm_agent_sampling_enabled=false

Etiqueta de período

Si se han especificado propiedades de regla o un archivo de configuración de muestreo y el muestreo no está desactivado, cada período raíz de rastreo muestreado tiene una etiqueta SamplingEvaluation del flujo de evaluación.

A continuación se muestra un ejemplo de un árbol de reglas utilizado para la evaluación:
rule: per-operation-rate
param: 5/60
false:
     rule: probabilistic
     param: 0.2

Valor de la etiqueta SamplingEvaluation

Consulte a continuación el valor de la etiqueta SamplingEvaluation del período raíz muestreado:

Valor de la etiqueta SamplingEvaluation Descripción
per-operation-rate(5/60):true Los 5 primeros rastreos muestreados cada 60 segundos.
per-operation-rate(5/60):false->probabilistic(0.2):true El 20 % de los rastreos muestreados después de 5 rastreos muestreados cada 60 segundos.