Sintaxis de regla de Información de colaboradores en CloudWatch

En esta sección se explica la sintaxis para las reglas de Contributor Insights. Utilice esta sintaxis solo cuando vaya a crear una regla introduciendo un bloque JSON. Si utiliza el asistente para crear una regla, no necesita conocer la sintaxis. Para obtener más información acerca de cómo crear reglas mediante el asistente, consulte Creación de una regla de Información de colaboradores en CloudWatch.

Todas las coincidencias de reglas para registrar valores y nombres de campo de evento distinguen entre mayúsculas y minúsculas.

En el ejemplo siguiente se ilustra la sintaxis de los registros JSON.

{
    "Schema": {
        "Name": "CloudWatchLogRule",
        "Version": 1
    },
    "LogGroupNames": [
        "API-Gateway-Access-Logs*",
        "Log-group-name2"
    ],
    "LogFormat": "JSON",
    "Contribution": {
        "Keys": [
            "$.ip"
        ],
        "ValueOf": "$.requestBytes",
        "Filters": [
            {
                "Match": "$.httpMethod",
                "In": [
                    "PUT"
                ]
            }
        ]
    },
    "AggregateOn": "Sum"
}

Campos en las reglas de Contributor Insights

Esquema

En el valor de Schema para una regla que analiza datos de CloudWatch Logs siempre debe ser {"Name": "CloudWatchLogRule", "Version": 1}

LogGroupNames

Una matriz de cadenas. Para cada elemento de la matriz, puede usar opcionalmente * al final de una cadena para incluir todos los grupos de registros con nombres que empiecen por ese prefijo.

Tenga cuidado con el uso de comodines con los nombres de los grupos de registro. Incurrirá en cargos por cada evento de registro que coincida con una regla. Si busca accidentalmente más grupos de registro de los que pretendía, puede incurrir en cargos inesperados. Para obtener más información, consulte Precios de Amazon CloudWatch.

LogGroupARNs

Si está creando esta regla en una cuenta de supervisión de observabilidad entre cuentas de CloudWatch, puede usar LogGroupARNs para especificar grupos de registro en las cuentas de origen que están vinculadas a la cuenta de supervisión y para especificar grupos de registro en la propia cuenta de supervisión. Debe especificar LogGroupNames o LogGroupARNs en la regla, pero no ambos.

LogGroupARNs es una matriz de cadenas. Para cada elemento de la matriz, tiene la opción de usar * como comodín en determinadas situaciones. Por ejemplo, puede indicar arn:aws:logs:us-west-1:*:log-group/MyLogGroupName2 para especificar los grupos de registro denominados MyLogGroupName2 en todas las cuentas de origen y en la cuenta de supervisión, en la región Oeste de EE. UU. (Norte de California). También puede indicar arn:aws:logs:us-west-1:111122223333:log-group/GroupNamePrefix* para especificar todos los grupos de registro del Oeste de EE. UU. (Norte de California) en 111122223333 que tengan nombres que comiencen por GroupNamePrefix.

Recuerde que no puede especificar un ID de cuenta parcial (AWS) como prefijo con un comodín.

Use con cuidado los comodines en los ARN de los grupos de registro. Incurrirá en cargos por cada evento de registro que coincida con una regla. Si busca accidentalmente más grupos de registro de los que pretendía, puede incurrir en cargos inesperados. Para obtener más información, consulte Precios de Amazon CloudWatch.

LogFormat

Los valores válidos son JSON y CLF.

Contribución

Este objeto incluye una matriz Keys con hasta cuatro miembros, una solo ValueOf de forma opcional y, también opcionalmente, una matriz de hasta cuatro Filters.

Claves

Una matriz de hasta cuatro campos de registro que se utilizan como dimensiones para clasificar los colaboradores. Si especifica más de una clave, cada combinación única de valores de las claves se cuenta como un colaborador único. Los campos deben especificarse utilizando la notación de formato de propiedad JSON.

ValueOf

(Opcional) Especifique esto solo cuando especifique Sum como valor de AggregateOn. ValueOf especifica un campo de registro con valores numéricos. En este tipo de regla, los colaboradores se clasifican según su suma del valor de este campo, en lugar de su número de apariciones en las entradas de registro. Por ejemplo, si desea ordenar a los colaboradores por sus valores de BytesSent totales durante un período, establezca ValueOf en BytesSent y especifique Sum para AggregateOn.

Filtros

(Opcional) Especifica una matriz de hasta cuatro filtros para restringir los eventos de registro que se incluyen en el informe. Si especifica varios filtros, Contributor Insights los evalúa con un operador AND lógico. Puede utilizar esto para filtrar eventos de registro irrelevantes en su búsqueda, o bien para seleccionar un solo colaborador a fin de analizar su comportamiento.

Cada miembro de la matriz debe incluir un campo Match y un campo que indique el tipo de operador coincidente que se debe usar.

El campo Match especifica un campo de registro para evaluar en el filtro. El campo de registro se especifica mediante la notación de formato de propiedad JSON.

El campo de operador coincidente debe ser uno de los siguientes: In, NotIn, StartsWith, GreaterThan, LessThan, EqualTo, NotEqualTo o IsPresent. Si el campo de operador es In, NotIn o StartsWith, va seguido de una matriz de valores de cadena que comprobar. Contributor Insights evalúa la matriz de valores de cadena con un operador OR. La matriz puede incluir hasta 10 valores de cadena.

Si el campo de operador es GreaterThan, LessThan, EqualTo o NotEqualTo, va seguido de un único valor numérico con el que comparar.

Si el campo de operador es IsPresent, va seguido de true o false. Este operador coincide con los eventos de registro en función de si el campo de registro especificado está presente en el evento de registro. isPresent funciona solo con valores en el nodo hijo de propiedades JSON. Por ejemplo, un filtro que busca coincidencias con c-count no evalúa un evento de registro con un valor de details.c-count.c1.

Vea los cuatro ejemplos de filtro siguientes:

{"Match": "$.httpMethod", "In": [ "PUT", ] }
{"Match": "$.StatusCode", "EqualTo": 200 }
{"Match": "$.BytesReceived", "GreaterThan": 10000}
{"Match": "$.eventSource", "StartsWith": [ "ec2", "ecs" ] }

AggregateOn

Los valores válidos son Count y Sum. Especifica si se debe agregar el informe en función de un recuento de apariciones o una suma de los valores del campo que se especifica en el campo ValueOf.

Notación de formato de propiedad JSON

Los campos Keys, ValueOf y Match siguen el formato de propiedad JSON con la notación de puntos, donde $ representa la raíz del objeto JSON. Esto va seguido de un punto y, a continuación, de una cadena alfanumérica con el nombre de la subpropiedad. Se admiten varios niveles de propiedad.

El primer carácter de la cadena solo puede ser A-Z o a-z. Los siguientes caracteres de la cadena pueden ser A-Z, a-z o 0-9.

En la lista siguiente se muestran ejemplos válidos de formato de propiedad JSON:

$.userAgent
$.endpoints[0]
$.users[1].name
$.requestParameters.instanceId

Campo adicional en las reglas de los registros para CLF

Los eventos de registro de Common Log Format (CLF) no tienen nombres para los campos como JSON. Para proporcionar los campos que se utilizarán para las reglas de Contributor Insights, un evento de registro CLF se puede tratar como matriz con un índice a partir de 1. Puede especificar el primer campo como "1", el segundo como "2", y así sucesivamente.

Para facilitar la lectura de una regla de un registro CLF, puede utilizar Fields. Esto le permite proporcionar un alias de nombre para las ubicaciones de campo CLF. Por ejemplo, puede especificar que la ubicación "4" es una dirección IP. Una vez especificada, se puede usar IpAddress como propiedad en Keys, ValueOf y Filters en la regla.

A continuación, se muestra un ejemplo de una regla de un registro CLF que utiliza el campo Fields.

{
    "Schema": {
        "Name": "CloudWatchLogRule",
        "Version": 1
    },
    "LogGroupNames": [
        "API-Gateway-Access-Logs*"
    ],
    "LogFormat": "CLF",
    "Fields": {
        "4": "IpAddress",
        "7": "StatusCode"
    },
    "Contribution": {
        "Keys": [
            "IpAddress"
        ],
        "Filters": [
            {
                "Match": "StatusCode",
                "EqualTo": 200
            }
        ]
    },
    "AggregateOn": "Count"
}