Esempi di processore di telemetria - Application Insights di Monitoraggio di Azure per Java

Articolo
10/15/2024

Questo articolo fornisce esempi di processori di telemetria in Application Insights per Java, inclusi gli esempi per includere ed escludere configurazioni. Include anche esempi per processori di attributi e processori di span.

Includere ed escludere esempi Span

In questa sezione viene illustrato come includere ed escludere gli span. Si apprenderà anche come escludere più span e applicare l'elaborazione selettiva.

Includi span

Questa sezione illustra come includere gli span per un processore di attributi. Il processore non elabora span che non corrispondono alle proprietà.

Una corrispondenza richiede che il nome span sia uguale a spanA o spanB.

Questi intervalli corrispondono alle proprietà di include e vengono applicate le azioni del processore:

Nome Span1: attributi 'spanA': {env: dev, test_request: 123, credit_card: 1234}
Nome Span2: attributi 'spanB': {env: dev, test_request: false}
Nome Span3: attributi 'spanA': {env: 1, test_request: dev, credit_card: 1234}

Questo span non corrisponde alle proprietà include e le azioni del processore non vengono applicate:

Nome Span4 : attributi 'spanC': {env: dev, test_request: false}

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
  "preview": {
    "processors": [
      {
        "type": "attribute",
        "include": {
          "matchType": "strict",
          "spanNames": [
            "spanA",
            "spanB"
          ]
        },
        "actions": [
          {
            "key": "credit_card",
            "action": "delete"
          }
        ]
      }
    ]
  }
}

Escludi span

Questa sezione illustra come escludere gli span per un processore di attributi. Questo processore non elabora span che corrispondono alle proprietà.

Una corrispondenza richiede che il nome span sia uguale a spanA o spanB.

Gli span seguenti corrispondono alle proprietà exclude e le azioni del processore non vengono applicate:

Nome Span1: attributi 'spanA': {env: dev, test_request: 123, credit_card: 1234}
Nome Span2: attributi 'spanB': {env: dev, test_request: false}
Nome Span3: attributi 'spanA': {env: 1, test_request: dev, credit_card: 1234}

Questo span non corrisponde alle proprietà exclude e vengono applicate le azioni del processore:

Nome Span4 : attributi 'spanC': {env: dev, test_request: false}

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
  "preview": {
    "processors": [
      {
        "type": "attribute",
        "exclude": {
          "matchType": "strict",
          "spanNames": [
            "spanA",
            "spanB"
          ]
        },
        "actions": [
          {
            "key": "credit_card",
            "action": "delete"
          }
        ]
      }
    ]
  }
}

Escludere span usando più criteri

Questa sezione illustra come escludere gli span per un processore di attributi. Questo processore non elabora span che corrispondono alle proprietà.

Una corrispondenza richiede che vengano soddisfatte le condizioni seguenti:

Nello span deve esistere un attributo (ad esempio env con valore dev).
Lo span deve avere un attributo con chiave test_request.

Gli span seguenti corrispondono alle proprietà exclude e le azioni del processore non vengono applicate.

Nome Span1: attributi 'spanB': {env: dev, test_request: 123, credit_card: 1234}
Nome Span2: attributi 'spanA': {env: dev, test_request: false}

Lo span seguente non corrisponde alle proprietà exclude e vengono applicate le azioni del processore:

Nome Span3: attributi 'spanB': {env: 1, test_request: dev, credit_card: 1234}
Nome Span4: attributi 'spanC': {env: dev, dev_request: false}

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
  "preview": {
    "processors": [
      {
        "type": "attribute",
        "exclude": {
          "matchType": "strict",
          "spanNames": [
            "spanA",
            "spanB"
          ],
          "attributes": [
            {
              "key": "env",
              "value": "dev"
            },
            {
              "key": "test_request"
            }
          ]
        },
        "actions": [
          {
            "key": "credit_card",
            "action": "delete"
          }
        ]
      }
    ]
  }
}

Elaborazione selettiva

Questa sezione illustra come specificare il set di proprietà di span che indica a quali span deve essere applicato questo processore. Le proprietà include indicano quali span devono essere elaborati. Le proprietà exclude filtrano gli intervalli che non devono essere elaborati.

Nella configurazione seguente, questi span corrispondono alle proprietà e vengono applicate le azioni del processore:

Nome Span1: attributi 'spanB': {env: production, test_request: 123, credit_card: 1234, redact_trace: "false"}
Nome Span2: attributi 'spanA': {env: staging, test_request: false, redact_trace: true}

Questi intervalli non corrispondono alle proprietà include e le azioni del processore non vengono applicate:

Nome Span3: attributi 'spanB': {env: production, test_request: true, credit_card: 1234, redact_trace: false}
Nome Span4 : attributi 'spanC': {env: dev, test_request: false}

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
  "preview": {
    "processors": [
      {
        "type": "attribute",
        "include": {
          "matchType": "strict",
          "spanNames": [
            "spanA",
            "spanB"
          ]
        },
        "exclude": {
          "matchType": "strict",
          "attributes": [
            {
              "key": "redact_trace",
              "value": "false"
            }
          ]
        },
        "actions": [
          {
            "key": "credit_card",
            "action": "delete"
          },
          {
            "key": "duplicate_key",
            "action": "delete"
          }
        ]
      }
    ]
  }
}

Esempi di processore di attributi

Inserisci

L'esempio seguente inserisce il nuovo attributo {"attribute1": "attributeValue1"} in span e log in cui la chiave attribute1 non esiste.

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
  "preview": {
    "processors": [
      {
        "type": "attribute",
        "actions": [
          {
            "key": "attribute1",
            "value": "attributeValue1",
            "action": "insert"
          }
        ]
      }
    ]
  }
}

Inserisci da un'altra chiave

Nell'esempio seguente viene usato il valore dell'attributo anotherkey per inserire il nuovo attributo {"newKey": "<value from attribute anotherkey>"} in span e log in cui la chiave newKey non esiste. Se l'attributo anotherkey non esiste, in span e log non viene inserito alcun nuovo attributo.

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
  "preview": {
    "processors": [
      {
        "type": "attribute",
        "actions": [
          {
            "key": "newKey",
            "fromAttribute": "anotherKey",
            "action": "insert"
          }
        ]
      }
    ]
  }
}

Update

L'esempio seguente aggiorna l'attributo a {"db.secret": "redacted"}. Aggiorna l'attributo boo usando il valore dell'attributo foo. Gli span e i log che non hanno l'attributo boo non cambiano.

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
  "preview": {
    "processors": [
      {
        "type": "attribute",
        "actions": [
          {
            "key": "db.secret",
            "value": "redacted",
            "action": "update"
          },
          {
            "key": "boo",
            "fromAttribute": "foo",
            "action": "update" 
          }
        ]
      }
    ]
  }
}

Elimina

Nell'esempio seguente viene illustrato come eliminare un attributo che ha la chiave credit_card.

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
  "preview": {
    "processors": [
      {
        "type": "attribute",
        "actions": [
          {
            "key": "credit_card",
            "action": "delete"
          }
        ]
      }
    ]
  }
}

Hash

Nell'esempio seguente viene illustrato come eseguire l'hash dei valori di attributo esistenti.

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
  "preview": {
    "processors": [
      {
        "type": "attribute",
        "actions": [
          {
            "key": "user.email",
            "action": "hash"
          }
        ]
      }
    ]
  }
}

Estrazione

Nell'esempio seguente viene illustrato come usare un'espressione regolare (regex) per creare nuovi attributi in base al valore di un altro attributo. Ad esempio, se url.path = /path?queryParam1=value1,queryParam2=value2, vengono inseriti gli attributi seguenti:

httpProtocol: http
httpDomain: example.com
httpPath: path
httpQueryParams: queryParam1=value1,queryParam2=value2
url.path: nessuna modifica

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
  "preview": {
    "processors": [
      {
        "type": "attribute",
        "actions": [
          {
            "key": "url.path",
            "pattern": "^(?<httpProtocol>.*):\\/\\/(?<httpDomain>.*)\\/(?<httpPath>.*)(\\?|\\&)(?<httpQueryParams>.*)",
            "action": "extract"
          }
        ]
      }
    ]
  }
}

Maschera

Ad esempio, se url.path = https://example.com/user/12345622 viene aggiornato a url.path = https://example.com/user/**** usando una delle configurazioni seguenti.

Primo esempio di configurazione:

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
  "preview": {
    "processors": [
      {
        "type": "attribute",
        "actions": [
          {
            "key": "url.path",
            "pattern": "user\\/\\d+",
            "replace": "user\\/****",
            "action": "mask"
          }
        ]
      }
    ]
  }
}

Secondo esempio di configurazione con il nome del gruppo di espressioni regolari:

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
  "preview": {
    "processors": [
      {
        "type": "attribute",
        "actions": [
          {
            "key": "url.path",
            "pattern": "^(?<userGroupName>[a-zA-Z.:\/]+)\d+",
            "replace": "${userGroupName}**",
            "action": "mask"
          }
        ]
      }
    ]
  }
}

Esempi di attributi tipizzati non stringa

A partire dalla versione 3.4.19 GA, i processori di telemetria supportano attributi tipizzati stringa: boolean, double long, boolean-array, double-array, long-array e string-array.

Quando attributes.type non viene fornito nel file JSON, per impostazione predefinita è string.

L'esempio seguente inserisce il nuovo attributo {"newAttributeKeyStrict": "newAttributeValueStrict"} negli span e log in cui gli attributi corrispondono agli esempi seguenti: {"longAttributeKey": 1234}{"booleanAttributeKey": true}{"doubleArrayAttributeKey": [1.0, 2.0, 3.0, 4.0]}

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
  "preview": {
    "processors": [
      {
        "type": "attribute",
        "include": {
          "matchType": "strict",
          "attributes": [
            {
              "key": "longAttributeKey",
              "value": 1234,
              "type": "long"
            },
            {
              "key": "booleanAttributeKey",
              "value": true,
              "type": "boolean"
            },
            {
              "key": "doubleArrayAttributeKey",
              "value": [1.0, 2.0, 3.0, 4.0],
              "type": "double-array"
            }
          ]
        },
        "actions": [
          {
            "key": "newAttributeKeyStrict",
            "value": "newAttributeValueStrict",
            "action": "insert"
          }
        ],
        "id": "attributes/insertNewAttributeKeyStrict"
      }
    ]
  }
}

Inoltre, gli attributi tipizzati non stringa supportano regexp.

Nell'esempio seguente il nuovo attributo {"newAttributeKeyRegexp": "newAttributeValueRegexp"} viene inserito negli span e log in cui l'attributo longRegexpAttributeKey corrisponde al valore da 400 a 499.

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
  "preview": {
    "processors": [
      {
        "type": "attribute",
        "include": {
          "matchType": "regexp",
          "attributes": [
            {
              "key": "longRegexpAttributeKey",
              "value": "4[0-9][0-9]",
              "type": "long"
            }
          ]
        },
        "actions": [
          {
            "key": "newAttributeKeyRegexp",
            "value": "newAttributeValueRegexp",
            "action": "insert"
          }
        ],
        "id": "attributes/insertNewAttributeKeyRegexp"
      }
    ]
  }
}

Esempi di processori di span

Assegnare un nome a span

Nell'esempio seguente vengono specificati i valori degli attributi db.svc, operation e id. Forma il nuovo nome dello span usando tali attributi, in tale ordine, separati dal valore ::.

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
  "preview": {
    "processors": [
      {
        "type": "span",
        "name": {
          "fromAttributes": [
            "db.svc",
            "operation",
            "id"
          ],
          "separator": "::"
        }
      }
    ]
  }
}

Estrarre attributi da un nome span

Si supponga che il nome dello span di input sia /api/v1/document/12345678/update. Nell'esempio seguente viene restituito il nome dello span di output /api/v1/document/{documentId}/update. Aggiunge allo span il nuovo attributo documentId=12345678.

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
  "preview": {
    "processors": [
      {
        "type": "span",
        "name": {
          "toAttributes": {
            "rules": [
              "^/api/v1/document/(?<documentId>.*)/update$"
            ]
          }
        }
      }
    ]
  }
}

Estrarre gli attributi da un nome di span usando includi ed escludi

Nell'esempio seguente viene illustrato come modificare il nome dello span in {operation_website}. Aggiunge un attributo con chiave operation_website e valore {oldSpanName} quando lo span ha le proprietà seguenti:

Il nome dello span contiene / in un punto qualsiasi della stringa.
Il nome dello span non è donot/change.

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
  "preview": {
    "processors": [
      {
        "type": "span",
        "include": {
          "matchType": "regexp",
          "spanNames": [
            "^(.*?)/(.*?)$"
          ]
        },
        "exclude": {
          "matchType": "strict",
          "spanNames": [
            "donot/change"
          ]
        },
        "name": {
          "toAttributes": {
            "rules": [
              "(?<operation_website>.*?)$"
            ]
          }
        }
      }
    ]
  }
}

Esempi di processore di log

Estrarre attributi dal corpo del messaggio di log

Si supponga che il corpo del messaggio del log di input sia Starting PetClinicApplication on WorkLaptop with PID 27984 (C:\randompath\target\classes started by userx in C:\randompath). Nell'esempio seguente viene restituito il corpo del messaggio di output Starting PetClinicApplication on WorkLaptop with PID {PIDVALUE} (C:\randompath\target\classes started by userx in C:\randompath). Aggiunge al log il nuovo attributo PIDVALUE=27984.

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
  "preview": {
    "processors": [
      {
        "type": "log",
        "body": {
          "toAttributes": {
            "rules": [
              "^Starting PetClinicApplication on WorkLaptop with PID (?<PIDVALUE>\\d+) .*"
            ]
          }
        }
      }
    ]
  }
}

Mascherare i dati sensibili nel messaggio di log

L'esempio seguente illustra come mascherare i dati sensibili in un corpo del messaggio di log usando sia il processore di log che il processore di attributi. Si supponga che il corpo del messaggio del log di input sia User account with userId 123456xx failed to login. Il processore di log aggiorna il corpo del messaggio di output in User account with userId {redactedUserId} failed to login e il processore di attributi elimina il nuovo attributo redactedUserId, che è stato aggiunto nel passaggio precedente.

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000",
  "preview": {
    "processors": [
      {
        "type": "log",
        "body": {
          "toAttributes": {
            "rules": [
              "userId (?<redactedUserId>[0-9a-zA-Z]+)"
            ]
          }
        }
      },
      {
        "type": "attribute",
        "actions": [
          {
            "key": "redactedUserId",
            "action": "delete"
          }
        ]
      }
    ]
  }
}

Domande frequenti

Perché i file di log del processore di log non usano TelemetryClient.trackTrace()?

TelemetryClient.trackTrace() fa parte del bridge di Application Insights Classic SDK e i processori di log funzionano solo con la nuova strumentazione basata su OpenTelemetry.

Condividi tramite