As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá. # Funções de solução de problemas e monitoramento Esta página ajuda você a diagnosticar erros comuns de função e monitorar o desempenho da função na produção. A seção de solução de problemas é organizada por sintoma — comece com o que você observa, depois siga a causa e corrija. ## Monitoramento ### CloudWatch métricas MediaTailor publica métricas para execução de funções na Amazon CloudWatch. Não é necessário optar por participar. **Hook-level métricas** — um ponto de dados por execução do gancho do ciclo de vida: | Métrica | Description | Dimensões | | --- | --- | --- | | PreSessionInitHook.Invocations | Contagem de execuções por gancho | ConfigurationName | | PreSessionInitHook.Errors | Contagem de erros de gancho | ConfigurationName | | PreSessionInitHook.Latency | Tempo de execução do gancho (ms) | ConfigurationName | | PreAdsRequestHook.Invocations | Contagem de execuções por gancho | ConfigurationName | | PreAdsRequestHook.Errors | Contagem de erros de gancho | ConfigurationName | | PreAdsRequestHook.Latency | Tempo de execução do gancho (ms) | ConfigurationName | **Function-level métricas** — um ponto de dados por execução de função individual: | Métrica | Description | Dimensões | | --- | --- | --- | | Function.Invocations | Contagem de execuções de funções | ConfigurationName, FunctionId, FunctionType, HookType | | Function.Errors | Contagem de erros de função | ConfigurationName, FunctionId, FunctionType, HookType | | Function.Latency | Tempo de execução da função (ms) | ConfigurationName, FunctionId, FunctionType, HookType | Para obter mais detalhes sobre como configurar alarmes e trabalhar com essas métricas, consulte[Monitoramento AWS Elemental MediaTailor com CloudWatch métricas da Amazon](monitoring-cloudwatch-metrics.md). ### Eventos de log MediaTailor emite eventos de log para execução da função. Os eventos de erro são emitidos por padrão. Eventos concluídos e resumidos são opcionais. | Tipo de evento | Padrão/ Opt-in | Grupo de registros | Description | | --- | --- | --- | --- | | PRE\_SESSION\_INIT\_HOOK\_SUMMARY | Opt-in | Registro do manifesto | Resumo da execução do gancho (success/error) | | PRE\_SESSION\_INIT\_HOOK\_ERROR | Padrão | Registro do manifesto | Falha no gancho com errorType e causa | | PRE\_SESSION\_INIT\_FUNCTION\_COMPLETED | Opt-in | Registro do manifesto | Função individual concluída com input/output | | PRE\_SESSION\_INIT\_FUNCTION\_ERROR | Padrão | Registro do manifesto | Falha de função individual | | PRE\_ADS\_REQUEST\_HOOK\_SUMMARY | Opt-in | Registro de interação do ADS | Resumo da execução do gancho (success/error) | | PRE\_ADS\_REQUEST\_HOOK\_ERROR | Padrão | Registro de interação do ADS | Falha no gancho com errorType e causa | | PRE\_ADS\_REQUEST\_FUNCTION\_COMPLETED | Opt-in | Registro de interação do ADS | Função individual concluída com input/output | | PRE\_ADS\_REQUEST\_FUNCTION\_ERROR | Padrão | Registro de interação do ADS | Falha de função individual | Para habilitar eventos de registro opcionais, consulte[Monitoramento AWS Elemental MediaTailor com CloudWatch métricas da Amazon](monitoring-cloudwatch-metrics.md). Use o `eventId` campo para correlacionar eventos em nível de gancho e em nível de função para a mesma execução. A seguinte consulta do Amazon CloudWatch Logs Insights filtra eventos de erro de função `eventId` para rastrear uma única execução: ``` fields @timestamp, eventType, functionId, errorType, cause | filter eventId = "5dc6f040-0f72-4e8c-a64e-25eeef62708c" | sort @timestamp asc ``` ## Solução de problemas Quando uma função falha, MediaTailor registra um `errorType` campo no evento de erro. Use esse campo para identificar a classe de falha: | Tipo de erro | Description | | --- | --- | | SYNTAX\_ERROR | A expressão falhou ao compilar ou encontrou um erro de tipo de tempo de execução | | RESOURCE\_LIMIT\_ERROR | A expressão excedeu os limites de tempo de CPU, memória ou profundidade da pilha | | RESTRICTION\_ERROR | A expressão usou uma função bloqueada ou o limite de tamanho da carga de entrada foi excedido | | TIMEOUT\_ERROR | A execução da função excedeu seu limite de tempo | | VALIDATION\_ERROR | O caminho de saída visa um campo não gravável no escopo do gancho atual | | INTERNAL\_ERROR | Falha na infraestrutura não relacionada à função | As entradas são organizadas por sintoma e fazem referência a esses tipos de erro quando aplicável. ### A expressão retorna null inesperadamente **Sintoma:** Um valor de saída que você esperava que fosse preenchido está `null` ou está ausente nos parâmetros do player. **Causas possíveis:** | Causa | Como identificar | Correção | | --- | --- | --- | | O campo de entrada não existe nesse gancho do ciclo de vida. | Você referenciou adsRequest.url em uma PRE\_SESSION\_INITIALIZATION função. Os dados da solicitação do ADS não estão disponíveis no início da sessão. | Mova a função para o gancho PRE\_ADS\_REQUEST do ciclo de vida ou use um campo de entrada diferente. Consulte [Hooks do ciclo de vida](monetization-functions-hooks.md). | | O campo de entrada está ausente dos dados da sessão. | Você fez referênciaplayer\_params.campaign\_id, mas o player não passou esse parâmetro na inicialização da sessão. | Use $exists() para verificar antes de acessar:{%$exists(player\_params.campaign\_id) ? player\_params.campaign\_id : 'default'%}. | | Você escreveu um objeto ou matriz nos parâmetros do player ou na solicitação do ADS. | Esses namespaces aceitam somente strings, números e booleanos. Objetos e matrizes são filtrados. | Armazene dados complexos temp.\* e extraia sequências de caracteres, números ou booleanos em uma etapa subsequente. | ### `RESOURCE_LIMIT_ERROR`: Stack overflow **Sintoma:** A função falha com `errorType: "RESOURCE_LIMIT_ERROR"` `cause: "Stack overflow error"` e. **Causa:** A expressão excedeu a profundidade máxima da pilha de 100 níveis. Isso normalmente acontece com expressões condicionais (if/then/else) profundamente aninhadas ou atribuições de variáveis complexas. Isso significa que a expressão tem muitos níveis de aninhamento MediaTailor para ser processada. **Correção:** simplifique a expressão. Divida a lógica complexa em várias entradas de saída ou várias etapas em um executor sequencial. ### `RESOURCE_LIMIT_ERROR: tempo limite` da CPU **Sintoma:** A função falha com `errorType: "RESOURCE_LIMIT_ERROR"` `cause: "Expression evaluation timeout: Check for infinite loop"` e. **Causa:** A expressão excedeu o limite de tempo de CPU de 100 ms. Isso pode acontecer com expressões que realizam cálculos caros em grandes estruturas de dados. **Correção:** reduza a complexidade da expressão. Se você estiver processando matrizes grandes, considere mover essa lógica para um serviço externo e chamá-la com uma `HTTP_REQUEST` função. ### `RESTRICTION_ERROR`: Função não permitida **Sintoma:** A função falha com `errorType: "RESTRICTION_ERROR"` `cause: "Function '' is not allowed"` e. **Causa:** A expressão chama uma função JSonata que não está na lista permitida de 38 funções. Exemplos comuns incluem `$filter``$reduce`, `$eval``$split`,, `$join` e. **Correção:** verifique o `cause` campo para ver o nome da função bloqueada. Substitua-o por uma alternativa permitida. Veja [Referência de expressão JSonata](monetization-functions-jsonata.md) a lista completa das 38 funções permitidas. As funções permitidas comumente usadas incluem `$string` `$number``$substring`,`$contains`,, `$encodeUrlComponent` e. ### `RESTRICTION_ERROR: Expressão` muito longa **Sintoma:** A função não consegue ser criada ou atualizada com`cause: "Expression length exceeds limit "`. **Causa:** Uma única expressão excede 1.000 caracteres. **Correção:** divida a expressão em partes menores. Use várias entradas de saída ou divida a lógica em várias etapas em um executor sequencial. Use vinculação variável (`:=`) para evitar a repetição de subexpressões longas. ### Erro HTTP: o código de status é nulo **Sintoma:** Na saída de uma `HTTP_REQUEST` função, `response.statusCode` é`null`. **Causa:** a API externa estava inacessível, a conexão atingiu o tempo limite ou ocorreu um erro na rede. Quando isso acontece, MediaTailor define `response.statusCode` como `null``null`, `response.body` para e `response.text` para`"Internal Error"`. **Correção:** sempre verifique `response.statusCode` antes de acessar os dados de resposta: ``` {%response.statusCode = 200 ? response.body.value : 'default'%} ``` Essa expressão verifica se a chamada HTTP retornou um código de status 200. Em caso afirmativo, ele usa o valor da resposta. Caso contrário, ele volta para um valor padrão. Se isso acontecer com frequência, verifique se a API externa está íntegra. Considere aumentar `RequestTimeoutMilliseconds` se a API estiver lenta ou diminuí-la se você quiser falhar rapidamente. ### Erro HTTP: o corpo da resposta é nulo **Sintoma:** `response.statusCode` é 200, mas `response.body` é`null`. **Causa:** o corpo da resposta não é um JSON válido ou tem mais de 20.000 caracteres. MediaTailor analisa apenas respostas JSON de até 20.000 caracteres. `response.body` **Correção:** use `response.text` como alternativa. O `response.text` campo contém o corpo bruto da resposta truncado para 20.000 caracteres: ``` {%response.statusCode = 200 ? ($exists(response.body.id) ? response.body.id : $substring(response.text, 0, 100)) : 'error'%} ``` Se os dados de que você precisa estiverem além do limite de 20.000 caracteres, considere pedir à API externa que retorne uma resposta menor (por exemplo, solicitando campos específicos). ### Erro HTTP: falha na validação do URL **Sintoma:** A função falha em tempo de execução com uma mensagem sobre a URL estar malformada, usando um esquema inválido ou excedendo o tamanho máximo. **Causas possíveis:** | Causa | Correção | | --- | --- | | O URL não usa http ouhttps. | Certifique-se de que a expressão do URL produza um URL começando com http:// ouhttps://. | | O URL excede 2.048 caracteres após a avaliação da expressão. | Encurte o URL. Mova valores de parâmetros grandes para o corpo da solicitação usando um método POST. | | O URL está incorreto (não é um URI válido). | Verifique se há caracteres ausentes ou extras na expressão. Use $encodeUrlComponent() para consultar valores de parâmetros que podem conter caracteres especiais. | ### `VALIDATION_ERROR` **Sintoma:** A função falha com`errorType: "VALIDATION_ERROR"`. Esse erro pode ocorrer no momento da criação (quando você cria ou atualiza a função) ou no momento da execução (quando a função é executada durante uma sessão). **Causas possíveis:** | Causa | Exemplo | Correção | | --- | --- | --- | | A chave de saída tem como alvo um namespace não gravável no gancho atual. | Escrevendo adsRequest.url em uma função anexada PRE\_SESSION\_INITIALIZATION a. | Verifique quais namespaces de saída são permitidos em seu gancho de ciclo de vida. PRE\_SESSION\_INITIALIZATIONsó permiteplayer\_params.\*. Mova a função para o gancho correto ou altere a chave de saída. Consulte [Hooks do ciclo de vida](monetization-functions-hooks.md). | | A chave de saída usa caracteres inválidos. | Uma chave de saída como player\_params.device type (com um espaço). Somente letras, números, sublinhados e hífens são permitidos. | Renomeie a chave de saída para usar somente caracteres válidos. Por exemplo, use player\_params.device\_type em vez disso. | | A chave de saída não começa com um prefixo válido. | Uma chave de saída como custom.myValue em vez de player\_params.myValue outemp.myValue. | Use um prefixo de saída válido:player\_params.\*,temp.\*, ouadsRequest.\*. | | Uma expressão JSonata tem um erro de sintaxe. | Uma citação de fechamento ausente ou uma condição incompleta:{%session.id & %}. | Examine a expressão em busca de aspas ausentes, parênteses sem correspondência ou operadores sem suporte, como ou. ?? ?: | | Falta um campo obrigatório em uma função HTTP\_REQUEST. | O campo URL está vazio ou o método não foi especificado. | Certifique-se de que os campos de URL e método estejam definidos. O método deve ser GET ouPOST. | | O URL criado pela expressão é inválido. | O URL avaliado usa um esquema não suportadoftp://, como, por exemplo, excede 2.048 caracteres ou está incorreto. | Verifique se a expressão do URL produz um https:// URL http:// ou válido. Use $encodeUrlComponent() para consultar valores de parâmetros que podem conter caracteres especiais. | | Um cabeçalho HTTP contém caracteres inválidos ou usa um nome restrito. | Um valor de cabeçalho contém quebras de linha ou o nome do cabeçalho é host outransfer-encoding. | Remova caracteres inválidos dos valores do cabeçalho. Evite nomes de cabeçalhos restritos. Consulte [HTTP\_REQUEST](monetization-functions-types-http-request.md) os limites do cabeçalho. | Verifique o `cause` campo no evento de registro de erros — ele identifica qual campo ou expressão falhou na validação. ### `INTERNAL_ERROR` **Sintoma:** A função falha com`errorType: "INTERNAL_ERROR"`. **Causa:** Ocorreu uma falha na infraestrutura que não está relacionada à configuração da função. **Correção:** repita a solicitação. Se o erro persistir, entre em contato com o AWS Support.