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, consulteMonitoramento AWS Elemental MediaTailor com CloudWatch métricas da Amazon.
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, consulteMonitoramento AWS Elemental MediaTailor com CloudWatch métricas da Amazon.
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. |
| 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
'<name>' 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 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 comcause: "Expression length <actual> exceeds limit
<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 nullnull, 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 comerrorType: "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. |
| 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 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 comerrorType: "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.
