Enriquecimento do Intervalo

Sobre o Enriquecimento do Intervalo

Capacite os usuários a enriquecer intervalos com atributos personalizados ou alterar, combinar ou remover dados de atributos existentes.
As operações de enriquecimento são definidas por meio de regras de intervalo que contêm uma ou mais ações a serem aplicadas em uma ordem específica em um determinado intervalo.
Há dois tipos de regras de intervalo: Personalizado e fornecido pela Oracle.
O enriquecimento do intervalo é configurado no nível de Domínio do APM.

Exemplos de Enriquecimento do Intervalo:

Remoção de Informações Pessoais Identificáveis (PII) de intervalos.
Combine dados de vários atributos em um único.
Extrair dados de um atributo. Por exemplo, um caminho parcial de um URL mais longo.
Aplicar funções matemáticas nos dados. Por exemplo, converta uma unidade de segundos em milissegundos.
Mapeie um valor de atributo para um novo valor. Por exemplo, mapeie o valor '1' para a cor 'blue', valor '2' para a cor 'red'.
Distribua valores numéricos em buckets. Por exemplo, um intervalo de valores de temperatura que é mapeado para os buckets 'frio', 'agente' e 'quente'.

Tópicos:

Uso do Enriquecimento do Intervalo

O Enriquecimento de Intervalo é configurado por meio de Regras de Intervalo que operam em um intervalo e são usados para modificar os atributos do intervalo. A caixa de ferramentas Regras de Intervalo fornece uma variedade de ações que podem ser executadas como parte de uma regra.

As Regras de Intervalo são gerenciadas dentro de grupos. Um grupo é um conjunto de regras que são aplicadas em uma ordem especificada. Cada regra pode aplicar uma ou mais ações em um intervalo e a saída de cada regra pode ser usada como entrada para regras de acompanhamento. Os grupos de regras exigem um Filtro de Intervalo usado para selecionar os intervalos nos quais as regras serão aplicadas.

Vários grupos podem ser definidos. Isso é útil quando você precisa manter diferentes tipos de regras para diferentes tipos de Intervalos, pois ele cria entidades lógicas com a funcionalidade projetada para uma finalidade específica. Isso reduz a complexidade geral do Conjunto de Regras.

Se vários grupos tiverem a configuração de Filtros de Intervalo que corresponderem ao mesmo intervalo, todos eles aplicarão suas regras a esse intervalo. A ordem em que é executada é determinada pela ordem alfabética dos nomes dos grupos. Lembre-se disso quando nomear ou renomear seus grupos. A Oracle recomenda prefixar os nomes com um número para evitar que os nomes de grupo sejam classificados em ordem alfabética. Por exemplo, "1. Remover Dados do Local", "2. Converter Unidades de Comprimento".

Lembre-se de que quando vários grupos estiverem operando no mesmo intervalo, isso significa que cada grupo operará em uma versão do intervalo que pode ter sido modificada por um grupo anterior na cadeia. Isso pode ser útil, pois você pode escrever regras em grupos de acompanhamento que dependem de modificações criadas por grupos anteriores. Por outro lado, também pode fazer com que as regras de acompanhamento falhem se um atributo com base em uma regra for removido ou modificado por um grupo anterior.

Observação

O valor acima só é importante quando um intervalo corresponde a mais de um grupo.

Se seus grupos tiverem filtros claramente desarticulados, um intervalo sempre será modificado por um único grupo e as considerações acima se tornarão irrelevantes.

Atributos em Eventos de Intervalo

Os intervalos podem conter uma lista de eventos que também são chamados de mensagens de log. Eles geralmente são usados para armazenar informações sobre momentos importantes durante a execução do intervalo. Por exemplo, se um intervalo descrever uma consulta de banco de dados, os eventos poderão ser gerados para marcar o momento em que a conexão foi aberta, quando a solicitação de consulta foi realmente enviada e quando a resposta foi recebida.

Um evento é identificado por name, timestamp e um conjunto de attributes (pares de chave/valor) que fornecem mais contexto para as informações gravadas.

Todas as ações da Regra de Intervalo descritas abaixo, que exigem um atributo como entrada ou saída, também podem ser aplicadas aos atributos de eventos individuais. Como os atributos de evento são independentes dos atributos de intervalo regulares, você precisará usar a seguinte sintaxe event reference para identificar o atributo de evento adequado:

event['NameOfEvent']:'NameOfAttribute'.

Observação

Os atributos de evento não podem ser usados como Filtros de Intervalo.

Criar e Gerenciar Regras de Intervalo

Você pode criar e gerenciar Regras de Intervalo, dependendo de suas necessidades de relatório.

Para criar Regras de Intervalo para um determinado domínio do APM, faça o seguinte:

Vá para a página Domínios do APM e clique no domínio do APM desejado.

A página Detalhes do Domínio é exibida.
Vá para Recursos, localizado na parte inferior esquerda e clique em Aprimoramento de Faixa.

O painel Aprimoramento de Faixa é exibido.
Clique em Criar grupo para criar um novo grupo de regras de intervalo.
O painel Criar grupo de regras de intervalo é exibido.
- Informe o Nome do novo grupo.
- Selecione um Filtro de Intervalo a ser usado com esse grupo.
- Opcionalmente, forneça uma Descrição para o novo grupo.
- Clique em Próximo para prosseguir para o painel Ações de regra para começar a adicionar regras de intervalo ao novo grupo, dependendo do tipo de regra de intervalo: Regra de intervalo personalizada ou Regra de intervalo fornecida pela Oracle.
- Informe o Nome da regra.
- Opcionalmente, selecione um Filtro de intervalo de regras para restringir ainda mais o escopo da operação da regra.
  
  Observação
  
  Os Filtros de Intervalo são criados separadamente. Para obter detalhes, consulte Filtros de Intervalo.
- Forneça opcionalmente uma Descrição da regra.
- Selecione um tipo de regra de intervalo.
  - Se você selecionar Regra de intervalo Fornecida pela Oracle, será oferecida uma lista de regras a serem escolhidas.
    
    As regras já foram criadas pela Oracle para ajudar os usuários. A lista inclui o seguinte:
    Adiciona o endereço IP do cliente a um intervalo.
    Ele adiciona o endereço IP do cliente a um intervalo como um atributo chamado ClientIP.
    
    Suíte EBS.
    Ele fornece o modelo do E-Business Suite.
    
    OpenTelemetry para conversão de nomeação do APM.
    Ele converte os nomes dos atributos de intervalo da convenção de nomenclatura OpenTelemetry para a convenção de nomenclatura do APM. Para obter informações sobre como usar OpenTelemetry com o APM, consulte Configurar Origens de Dados OpenTelemetry.
    Clique em uma regra na lista para adicioná-la ao grupo.
    
    Observação
    
    Não é possível configurar nenhuma ação, pois elas são gerenciadas internamente pela própria regra. Além disso, não é possível ver quais ações são para uma regra fornecida pela Oracle.
  - Se você optar por criar uma Regra de intervalo personalizada, será necessário definir uma ou mais ações para ela. (Uma regra sempre contém pelo menos uma ação).
    Antes de escolher uma Ação, você precisa selecionar um Destino da ação e um Tipo de ação.
    
    O Alvo da ação especifica a parte do intervalo no qual a ação opera. Existem dois destinos disponíveis:
    
    Entidade: Direcione todo o intervalo.
    
    Atributo: Direcione um único atributo.
    
    O Tipo de ação especifica o tipo. É usado principalmente para agrupar ações logicamente juntas. Por exemplo, string ou numérico.
    
    Agora selecione a ação apropriada na lista suspensa Ações Disponíveis.
    Como as ações têm vários contextos, a janela será alterada de acordo com cada tipo de ação. Para obter mais detalhes sobre ações, consulte Trabalhando com Ações.
    Para obter mais informações sobre as ações disponíveis para Alvo da ação e Tipo de ação, consulte Ações Disponíveis.
    Use o botão Adicionar Ação para adicionar mais ações à regra.
    
    Use o menu do item de ação no canto superior direito de cada Ação para movê-lo para cima ou para baixo na ordenação de regras ou excluir uma ação.

Trabalhando com Ações

As ações que têm um destino de Atributo sempre exigem que você forneça o nome do atributo cujo valor será usado como entrada para a ação. A janela de configuração de cada ação se refere a ela como Input Attribute.

Algumas ações também exigem que você forneça o nome de um atributo no qual armazenar o resultado da operação. Isso é chamado de Output Attribute. Se o atributo existir no intervalo, qualquer valor que ele tenha nesse momento será substituído pelo resultado da ação. Se ele ainda não existir, ele será adicionado ao intervalo com o novo valor. Você pode usar esse mecanismo para substituir o valor de qualquer atributo no intervalo (mesmo o atributo de entrada) pelo resultado da operação da ação.

Usando isso, você pode alimentar os resultados de qualquer ação para uma ação de acompanhamento (ou mesmo uma regra dentro do mesmo grupo de regras).

Também é possível usá-lo para armazenar valores em atributos temporários que podem ser usados por regras ou ações de acompanhamento, mas sem a necessidade de mantê-los como parte do resultado final. Apenas certifique-se de remover os atributos temporários como última etapa usando a ação Remover Atributo.

Observação

Uma ação Bloco rejeita o intervalo e não é possível usá-lo posteriormente, mesmo de outro Grupo de Regras.

Ações Disponíveis

Alvo da ação	Tipo de Ação	Ações Disponíveis
Entidade	Passthrough Ações que controlam se o intervalo em sua totalidade é passado ou bloqueado. Os intervalos bloqueados são rejeitados do pipeline de processamento. Os intervalos rejeitados não serão mais processados pelo APM, não serão armazenados em nenhum lugar e não estarão disponíveis para visualização posterior em outras ferramentas ou painéis do APM.	Bloco: Bloqueia esse intervalo incondicionalmente. Nenhuma ação e regra de acompanhamento será aplicada a ela e o intervalo não estará mais disponível nas ferramentas e produtos do APM OCI. Amostra: Amostras (aceita) se expandem com base em uma porcentagem de amostra. Por exemplo, um percentual de amostra de 25% aceitará (aleatoriamente) 25% de todos os intervalos e bloqueará o restante. Os intervalos bloqueados aqui são tratados da mesma forma que os intervalos bloqueados pela ação Bloquear.
Atributo	String Ações que permitem várias operações no valor do atributo, que é uma string. Por exemplo, alterando o caso, substituindo um valor ou extraindo uma parte da string.	Anexar: Anexa uma string estática ao valor de um atributo usando uma string de separador opcional. Concatenar: Concatena dois valores de atributo. Uma string de separador opcional pode ser fornecida na qual os valores serão unidos. O resultado é retornado como um novo atributo. Extrair: extrai uma parte do valor de um atributo com base em uma expressão regular. O resultado é retornado como um novo atributo. A expressão regular deve conter um operador de grupo de captura que identifica a parte da string a ser capturada. Se a expressão regular não corresponder, ou não houver grupo de captura, a ação não produzirá saída. Opcionalmente, você pode fornecer um valor de fallback, que será usado como saída da ação caso a própria extração não tenha produzido nenhum resultado. Minúsculas: Converte o valor de um atributo para minúsculas. Pesquisar e Substituir: Substitui uma ou mais partes do valor de um atributo usando uma expressão regular. A string corrigida é retornada como um novo atributo. A expressão regular pode conter um grupo de captura. Sem um grupo de captura, o conteúdo completo do que a expressão corresponde será substituído. Quando um grupo de captura estiver presente, somente o conteúdo capturado pelo grupo será substituído. A ocorrência de correspondência opcional poderá ser usada se apenas uma ocorrência específica de uma correspondência precisar ser substituída. Se esta opção não estiver definida ou definida como 0, todas as ocorrências correspondentes serão substituídas. Este é o procedimento default. Trim: Examina qualquer espaço inicial e final do valor de um atributo. Maiúsculas: converte o valor de um atributo para maiúsculas.
Atributo	Numérico Ações que permitem várias operações matemáticas nos valores de atributo (desde que sejam números). As ações numéricas suportam números reais e números representados como strings no valor do atributo, ou seja, os dois a seguir são equivalentes: "montante": 2,5 "montante" : "2,5" As ações numéricas podem tomar como entrada uma string que representa o nome de um atributo cujo valor será usado na operação ou um número que será usado diretamente no cálculo. Todas as ações numéricas têm uma opção na qual você pode aplicar arredondamento ao valor de saída. O arredondamento pode ser um dos seguintes: Arredondar: Arredonda o número para cima ou para baixo até o número inteiro mais próximo. Piso: Arredonda o número para baixo até o número inteiro mais próximo. Ceil: Arredonda o número para cima até o número inteiro mais próximo. Sem arredondamento: Opção padrão.	Absoluto: Retorna o valor absoluto do valor de entrada. Adicionar: Soma dois valores. Bucketize: Mapeia um valor de atributo numérico em nomes de bucket. Se o valor do atributo estiver dentro do intervalo de um bucket, o nome do bucket será retornado. Se nenhum bucket corresponder, um valor de fallback será retornado. Divida: Divide o primeiro pelo segundo valor. Se o segundo valor for 0, o resultado será 0. Máximo: Retorna o máximo dos dois valores. Mínimo: Retorna o mínimo dos dois valores. Multiplicar: Multiplica os dois valores. Negar: Nega (altera o sinal) do valor. Subtrair: Subtrai o segundo do primeiro atributo.
Atributo	Genérico Ações genéricas fornecem operações em nível de atributo, como remover um atributo do intervalo.	Mapear valor do atributo: Usa o valor de um atributo e o mapeia para um novo valor. Remover atributo: Remove o atributo do intervalo. Se o atributo for uma referência de nome de evento, `event['EventName']`, todo o evento de intervalo será removido. Renomear atributo: Renomeia o atributo. Definir atributo: Define um atributo para um valor estático. Se o atributo não existir, ele será adicionado; caso contrário, será atribuído o novo valor, substituindo o existente.

Exemplos de Configuração de Ação

Esta seção fornece exemplos das etapas de configuração necessárias para algumas ações individuais.

Exemplo de Bucketize:
Esta ação usa um minieditor para configurar vários buckets e seus valores de limite. Você pode usar o controle à direita para criar, atualizar e remover buckets.

Os buckets são ordenados automaticamente com base em seus valores de limite. Um valor de fallback é usado quando um valor é muito grande para o último bucket. A imagem a seguir mostra um exemplo com cinco buckets e um valor de fallback:
Exemplo de Mapa:
Esta ação usa um minieditor para configurar o mapa de pares de valores de entrada/saída. Os dois valores podem ser números ou strings. Use o controle à direita para criar, atualizar e/ou remover um mapeamento.
O botão Exportar permite fazer download de qualquer mapeamento para um arquivo (no formato CSV) para o computador.
O botão Importar permite que você preencha os mapeamentos de um arquivo CSV no computador. Isso é particularmente útil se você tiver um grande número de mapeamentos.

Validação das Regras de Aprimoramento do Intervalo

As configurações de enriquecimento de intervalo podem ser complexas de gravação e, às vezes, pode ser difícil saber antecipadamente se uma regra ou grupo de regras funcionará conforme esperado. Para ajudar com isso, o Editor de Configuração de Aprimoramento de Intervalo fornece uma opção para testar uma regra ou um grupo de regras em um intervalo de amostra antes de salvá-lo.

Para usar a opção de teste, faça o seguinte:

Selecione um grupo e clique em Editar para abrir o painel Editar grupo de regras de intervalo. Outra forma é criar um novo grupo e o painel Editar é exibido.
Clique na etapa Configurar ações de regra.
Clique em Testar para testar todo o grupo de regras. Como alternativa, para testar uma regra individual, selecione a regra e clique em Testar regra.
Observação

A regra de teste não está disponível quando o grupo de regras contém apenas uma regra.
O painel Testar grupo de regras de intervalo será exibido.
As regras a serem testadas serão mostradas com uma caixa de seleção ao lado delas. Você pode alterná-los conforme desejado.
Informe um intervalo de amostra na caixa de texto Amostra de intervalo.
Clique em Testar intervalo para executar um teste das regras selecionadas no intervalo fornecido.

Figura 9-1 Validação da Regra de Enriquecimento do Intervalo

A execução de teste informará se o intervalo corresponde ou não aos filtros de intervalo configurados.

Se os filtros corresponderem, as regras serão aplicadas ao intervalo e as diferenças resultantes (se houver) serão exibidas na tabela abaixo. Todos os atributos adicionados como resultado da regra serão destacados em verde. Os atributos que foram removidos serão destacados em vermelho. Os atributos modificados serão destacados em amarelo.

Trace Explorer: Para obter amostras precisas de intervalos do seu tráfego, clique em Trace Explorer localizado na parte superior direita para abrir o Trace Explorer e ver os intervalos reais que foram processados. Você pode selecionar um intervalo, abrir o menu de contexto à direita (os três pontos verticais) e clicar em Copiar dados do intervalo raiz.

Um pop-up é exibido com o conteúdo do intervalo. Você pode copiar os dados de intervalo e usá-los durante o teste.

Outra opção é colar seus próprios intervalos ou inseri-los manualmente, desde que estejam em conformidade com o formato de intervalo conforme reportado pelo Trace Explorer.

Aliases da Propriedade do Intervalo

Observação

Algumas das propriedades de intervalo reais são referenciadas por outro nome quando usadas nos recursos Aprimoramento de Intervalo ou Filtros de Intervalo. Além da diferença visual, isso não afeta a forma como você configura suas regras e filtros. Por exemplo, você sempre deve usar o alias ao fazer referência à propriedade fornecida.

Aqui estão as propriedades que atualmente têm um alias:

Propriedade do Intervalo	Alias de Enriquecimento de Intervalo	Comentários
`td-micros`	`SpanDuration`	`td-micros` está em microssegundos, enquanto `SpanDuration` está em milissegundos. A conversão da unidade de tempo é aplicada automaticamente por Enriquecimento de Intervalo e Filtros de Intervalo.
`name`	`OperationName`	O nome do intervalo representa a operação executada
`ts-micros`	`StartTime`	`ts-micros` está em microssegundos, enquanto `StartTime` está em milissegundos. A conversão da unidade de tempo é aplicada automaticamente por Enriquecimento de Intervalo e Filtros de Intervalo.
`id`	`SpanId`
`parent-id`	`ParentId`
`trace-id`	`TraceId`

Documentação do Oracle Cloud Infrastructure

Enriquecimento do Intervalo