Extracción de parámetros de negocio para su aplicación Python - Cloud Monitor

Application Real-Time Monitoring Service (ARMS) permite extraer parámetros de negocio de forma no intrusiva a partir de las trazas de llamadas de aplicaciones Python. Configure reglas de extracción en la consola de ARMS para escribir parámetros específicos de solicitudes y respuestas HTTP en Span Attributes, sin necesidad de modificar el código de la aplicación. Los atributos extraídos le ayudan a localizar causas raíz, rastrear información de solicitudes y activar marcados de error personalizados en los Spans coincidentes.

Requisitos previos

El agente de Python de ARMS está instalado en la aplicación Python.
La versión del agente de Python es 3.1.0 o posterior.

Alcance compatible

La siguiente tabla describe los tipos de extracción de parámetros y los orígenes compatibles con la versión de Python.

Tipo de extracción de parámetros	Origen del parámetro	Frameworks compatibles	Descripción
Solicitud de servidor HTTP	Header, Query Parameter, Cookie, Body	Flask, Django, FastAPI	El cuerpo debe estar en formato JSON. Para más información, consulte FAQs.
Respuesta de servidor HTTP	Header, Body, Cookie	Flask, Django, FastAPI	El cuerpo debe estar en formato JSON. El origen Cookie lee la cookie del lado de la solicitud.
Solicitud de cliente HTTP	Header, Query Parameter	requests, httpx, aiohttp, urllib3	El cliente no admite orígenes Body ni Cookie.
Respuesta de cliente HTTP	Header	requests, httpx, aiohttp, urllib3	-

Si el origen de parámetros que necesita no se encuentra dentro del alcance compatible, agregue instrumentación personalizada mediante el SDK de OpenTelemetry para escribir parámetros de negocio como Attributes en un Span.

Acceso a la página de configuración

Inicie sesión en la consola de ARMS.
En el panel de navegación izquierdo, elija Application Monitoring > Application List. En la barra de menú superior, seleccione la región objetivo y luego haga clic en el nombre de la aplicación Python deseada.
En el panel de navegación izquierdo, haga clic en Configuration. A continuación, haga clic en la pestaña Parameter Extraction Rule.

La página de configuración contiene dos secciones:

Parameter Extraction Rule — Cree, consulte y modifique reglas de extracción de parámetros de negocio. El agente de ARMS detecta dinámicamente los cambios en las reglas y extrae los parámetros de negocio basándose en todas las reglas habilitadas.
Custom Error Settings — Configure reglas de error personalizadas para coincidir con los valores de parámetros de negocio extraídos. Si se encuentra una coincidencia, el Span correspondiente se marca como error.

Creación de una regla de extracción

En la sección Parameter Extraction Rule, realice los siguientes pasos:

Haga clic en Create Rule.
Introduzca un nombre de regla y un nombre de Attribute.
Seleccione un tipo de extracción de parámetros, configure la interfaz activa y especifique el alcance de la interfaz para la regla.
En la sección de reglas de extracción de parámetros, agregue orígenes de parámetros y configure los pasos de procesamiento. Es posible configurar varios orígenes y pasos de procesamiento. Si múltiples orígenes pueden extraer el parámetro, el origen listado primero tiene mayor prioridad.
Establezca si desea habilitar la regla y luego haga clic en Save.

Importante

La primera vez que cree una regla de extracción, deberá reiniciar la aplicación para que la función surta efecto. Las adiciones o modificaciones posteriores de reglas no requieren reinicio. Las reglas se entregan dinámicamente mediante la actualización de configuración en caliente del agente y surten efecto en un plazo de 1 a 2 minutos.

Una vez creada y habilitada una regla, esta se entrega al agente de Python de ARMS en tiempo real. Los parámetros de negocio extraídos se registran en los Attributes de la traza de llamada correspondiente al Span. Puede filtrar y consultar los parámetros en la página de análisis de trazas. Los nombres de los Attributes tienen el prefijo biz. de forma predeterminada. No se permiten nombres de Attributes duplicados.

Configuración de reglas

Parámetro	Descripción
Nombre de la regla	Un nombre legible para humanos asignado a la regla.
Nombre del Attribute	El nombre del Span Attribute para el valor extraído. El nombre comienza con `biz.` de forma predeterminada, seguido de varias palabras. Cada palabra solo puede contener letras, dígitos, guiones (-) y guiones bajos (_). Las palabras deben separarse con puntos (.). Se permite un máximo de 10 palabras.
Tipo de extracción de parámetros	El tipo de parámetro a extraer (solicitud/respuesta de servidor HTTP, solicitud/respuesta de cliente HTTP).
Interfaz activa	El alcance de la interfaz para la regla. El agente extrae parámetros únicamente de las interfaces que coinciden con esta regla. Para más información, consulte How the active interface matches.
Regla de extracción de parámetros	El origen y el método de procesamiento del parámetro. Puede configurar varios orígenes de parámetros y pasos de extracción. Si múltiples orígenes pueden extraer el parámetro, el origen listado primero tiene mayor prioridad.
Origen del parámetro	El origen real del parámetro (Header, Query Parameter, Cookie o Body).
Pasos de procesamiento de parámetros	Pasos secuenciales de procesamiento para analizar sintácticamente el origen del parámetro y extraer el valor final. Puede agregar varios pasos. La salida del paso anterior se convierte en la entrada del siguiente. Si no se agrega ningún paso de procesamiento, el valor extraído será el texto JSON del objeto de origen.
Enable	Especifica si se debe habilitar la regla.

Métodos de procesamiento de parámetros

La siguiente tabla describe los métodos de procesamiento de parámetros compatibles con la versión de Python.

Método de procesamiento	Entrada	Salida	Descripción
JsonPath	Cadena JSON u objeto JSON	Cadena	Admite sentencias JsonPath con notación de punto. Si coinciden varios valores, se utiliza el primero. Ejemplo: `$.data.code`.
Regex	Cadena	Cadena	Admite expresiones regulares con grupos con nombre. La subcadena a extraer corresponde a un grupo llamado `res`. Se utiliza semántica de coincidencia completa (la expresión regular debe coincidir con toda la entrada, no es una búsqueda de subcadenas). Ejemplo: `.from:(?<res>[a-z]+).`.

Funcionamiento de la coincidencia de interfaz activa

El objetivo de coincidencia es el nombre del Span, con el formato Request method Route, como POST /api/order o GET /api/user/{id}. Tenga en cuenta lo siguiente:

Equals /api/order no coincide. Configúrelo como Equals POST /api/order en su lugar.
Alternativamente, utilice Ends with /api/order.
O bien use la expresión regular .*/api/order (las expresiones regulares también utilizan semántica de coincidencia completa).

Procesamiento de valores

Truncamiento — Si un valor extraído supera el límite máximo de longitud (100 caracteres de forma predeterminada), se trunca y se le añade ... al final. Para extraer campos Body más largos, aumente el límite de longitud del valor extraído.
Fusión de valores múltiples — Si existen varios valores para el mismo nombre de Header o Query Parameter, se fusionan en una cadena con el formato [a,b,c].
Desensibilización — Si la desensibilización está habilitada, el valor extraído se reemplaza por ***.
Cookie — Si varias cookies tienen el mismo nombre, se utiliza el último valor. El origen Cookie en la fase de respuesta lee la cookie del lado de la solicitud.

Verificación de la configuración

Una vez configurada una regla de extracción de parámetros, esta surte efecto inmediatamente (excepto la primera regla, que requiere reiniciar la aplicación). Para comprobar que la extracción funciona correctamente:

Localice el nombre del Attribute para la nueva regla. Por ejemplo, si estableció el nombre del Attribute como orderCode, el nombre completo del Attribute será biz.orderCode.
En la página de análisis de trazas, agregue el nombre del Attribute con el formato attributes.<Attribute name> (por ejemplo, attributes.biz.orderCode) como condición de consulta para filtrar los Spans relevantes.
Haga clic en una traza y revise el panel de Span Attributes. Si el atributo biz.orderCode aparece con el valor extraído esperado, la regla de extracción ha surtido efecto.

Gestión de reglas

Habilitar o deshabilitar una regla — Active o desactive el interruptor Enable en el lado derecho de la regla objetivo.
Editar o eliminar una regla — Haga clic en Edit o Delete en el lado derecho de la regla objetivo.
Eliminación por lotes — Seleccione las reglas de extracción que desea eliminar y luego haga clic en Batch Delete.
Copia por lotes — Seleccione las reglas de extracción que desea copiar y luego haga clic en Batch Copy to Other Applications. En el cuadro de diálogo, seleccione si desea copiar las reglas a todas las demás aplicaciones o solo a aplicaciones específicas.
- La copia por lotes tarda entre 1 y 2 minutos en surtir efecto.
- Solo se copian las reglas de extracción de parámetros. Las reglas de error personalizadas asociadas no se copian a la aplicación destino.
- Una regla no se copia si la aplicación destino ya tiene una regla con el mismo nombre de Attribute.

Preguntas frecuentes

¿Qué causa fallos en la extracción de parámetros?

El tipo de extracción de parámetros o el origen no están dentro del alcance compatible (por ejemplo, el origen Body o Cookie para el cliente). Consulte Supported scope para verificar si el framework y el origen actuales son compatibles.
La regla de coincidencia de interfaz activa está mal configurada. El objetivo de coincidencia es el nombre del Span con el formato Request method Route. Una regla como Equals /api/order no coincidirá. Consulte How the active interface matches.
La sintaxis del paso de procesamiento de parámetros es incorrecta, o el tipo de entrada no cumple con los requisitos del método de procesamiento:
- Regex debe contener un grupo con nombre llamado res y utiliza semántica de coincidencia completa. Para hacer coincidir una subcadena, agregue .* en ambos lados.
- La entrada para JsonPath debe ser un objeto JSON o texto JSON. Ejecutar JsonPath sobre una cadena simple (como el valor de Header abc) no produce ningún resultado.
La versión del agente de Python es anterior a la 3.1.0, la cual no admite la extracción de parámetros de negocio.
No se reinició la aplicación después de crear la primera regla.

¿Qué causa fallos en la extracción de Body?

Para evitar afectar la lectura propia que hace la aplicación del cuerpo de la solicitud o respuesta, el agente realiza una verificación de admisión antes de leer el Body. Si no se cumple alguna de las siguientes condiciones, el origen Body se omite por completo (no se trunca antes del análisis sintáctico):

Content-Type no es JSON — Solo se admiten application/json o tipos de medios que terminan con +json. No se extraen tipos como text/plain, application/x-www-form-urlencoded, multipart/form-data ni tipos binarios.
Content-Length falta o excede el límite — Si el encabezado de la solicitud no contiene Content-Length (por ejemplo, codificación de transferencia fragmentada), o si la longitud del Body supera el límite superior (64 KB de forma predeterminada), se omite todo el Body.
Body no es JSON válido codificado en UTF-8 — Si falla la decodificación o el análisis sintáctico de JSON, se omite el Body.
Respuesta en streaming — Las respuestas streaming de Flask o direct_passthrough, StreamingHttpResponse de Django y StreamingResponse de FastAPI/Starlette (incluido SSE) no extraen el Body de la respuesta.

A continuación se describen escenarios específicos de cada framework:

FastAPI — El Body de la solicitud solo es visible cuando la aplicación realmente lo lee; es decir, cuando el endpoint declara un parámetro Body (como un modelo Pydantic o Body()), o cuando el código llama a await request.body() o await request.json(). Si el endpoint no lee el cuerpo de la solicitud, el agente no consume activamente el flujo de la solicitud y no se puede extraer el Body.
Django — Si la aplicación consume primero el flujo de la solicitud mediante request.read() (lo que desencadena RawPostDataException), o si el Body supera el límite DATA_UPLOAD_MAX_MEMORY_SIZE de Django (lo que desencadena RequestDataTooBig), no se podrá extraer el Body. La lectura normal a través de request.body no se ve afectada (Django almacena el cuerpo en caché, por lo que la aplicación aún puede leerlo normalmente).
Flask — El agente lee y almacena en caché el cuerpo de la solicitud mediante request.get_data(cache=True). Posteriormente, la aplicación aún puede leer el cuerpo con normalidad, sin limitaciones adicionales.

¿Qué sucede si el valor extraído no coincide con lo esperado?

El valor termina con ...: El valor superó el límite de longitud del valor extraído (100 caracteres de forma predeterminada) y fue truncado. Aumente el límite de longitud.
El valor es ***: La desensibilización está habilitada para esta regla o de manera global.
El valor tiene el formato [a,b]: Existen múltiples valores para el mismo Header o Query Parameter y fueron fusionados.
Cuando JsonPath coincide con varios nodos, solo se devuelve el primer resultado.
Cuando varias reglas escriben en el mismo nombre de Attribute, la regla aplicada posteriormente sobrescribe a la anterior.

¿Puedo usar el origen Query Parameter para extraer campos de formulario de un Body de solicitud codificado como formulario?

No. Cuando el Content-Type de la solicitud es application/x-www-form-urlencoded, el origen Query Parameter se omite por completo para evitar que el agente active el análisis sintáctico de formularios del framework y afecte la lectura propia que hace la aplicación del cuerpo de la solicitud. Para dichos parámetros, páselos a través de cadenas de consulta URL o Headers en su lugar, o agregue instrumentación personalizada como se describe en la siguiente pregunta.

¿Cómo extraigo orígenes de parámetros de negocio no compatibles con la versión de Python?

Agregue instrumentación personalizada mediante el SDK de OpenTelemetry para aplicaciones Python con el fin de escribir parámetros de negocio como Attributes en un Span.