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
- 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 |
Agente de APM |
|
|
Creador de rastreador Actualice el creador de rastreador. |
Rastreador de APM |
|
|
Propiedades del sistema Actualiza las propiedades del sistema. |
Agente de APM y rastreador de APM |
|
|
Variables de entorno Actualiza las variables de entorno. |
Agente de APM y rastreador de APM |
|
Para Windows:
Para Linux:
|
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 |
|
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:
Para Linux:
|
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.
- 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 |
---|---|
|
Nodo que representa una matriz de configuración de muestreo diferente. |
|_ |
Elemento de matriz de configuración de muestreo. |
|____ |
Nodo de nombres de servicio al que se aplica esta configuración de muestreo. |
|_______ |
Elemento de matriz de nombre de servicio. |
|____ |
(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 |
|_______ |
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 |
|_______ |
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 |
|_______ |
Ignore el muestreo del intervalo de agente de APM local del principal especificado. Para ver los valores |
|____ |
Nodo de muestreo de base.
Es opcional si se utiliza el nodo |
|_______ |
Árbol de reglas de muestreo de esta configuración. |
|____ |
Matriz de nombres de operaciones con reglas que sustituyen la regla de muestreo base. |
|_______ |
Nombre para coincidir con nombre de operación del período raíz de rastreo. |
|_______ |
Regla que se aplicará si hay coincidencia. |
|_______ |
Expresión regular para coincidir con el nombre de operación del período raíz de rastreo. |
|_______ |
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. |
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
- Regla que se aplica a todos los servicios
sampling_config: - sampling: # Every trace has 2% chance to be sampled. rule: probabilistic param: 0.02
- 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
- 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
- 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 |
|
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:
Para Linux:
|
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.
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. |