AWS mediatailor: MediaTailor monetization functions: new hook metrics, log events, and troubleshooting
Summary
Adds six new hook execution metrics (invocations, errors, latency for post-ads-response and pre-manifest-insertion hooks), eight new ADS interaction log event types (hook summaries, hook errors, per-function completion/error events), a note that the JSONata sandbox now allows 44 functions (with $eval, $assert, $error, $sift cited as blocked examples instead of $filter, $reduce, $split, $join), plus two new troubleshooting sections about ad list changes having no effect and injected ads not appearing in the manifest.
Security assessment
The only security-tangential element is the expansion of the JSONata allow-list from 38 to 44 functions while still blocking dangerous/error-generating functions such as $eval, $assert, $error, and $sift — a sandbox-hardening detail, but it is presented as troubleshooting guidance rather than a documented security control, is not tied to any disclosed vulnerability or CVE, and the remaining changes (hook metrics, ADS interaction log events, mutable/injection-limit guidance) are operational observability and monetization behavior documentation only.
Evidence
+**Cause:** The expression calls a JSONata function that is not in the allowed list of 44 functions. Common examples include `$eval`, `$assert`, `$error`, `$sift`.
Diff
diff --git a/mediatailor/latest/ug/monetization-functions-troubleshooting.md b/mediatailor/latest/ug/monetization-functions-troubleshooting.md index 907206ca6..859382b39 100644 --- a//mediatailor/latest/ug/monetization-functions-troubleshooting.md +++ b//mediatailor/latest/ug/monetization-functions-troubleshooting.md @@ -28,0 +29,6 @@ Metric| Description| Dimensions +`PostAdsResponseHook.Invocations`| Count of hook executions| `ConfigurationName` +`PostAdsResponseHook.Errors`| Count of hook errors| `ConfigurationName` +`PostAdsResponseHook.Latency`| Hook execution time (ms)| `ConfigurationName` +`PreManifestInsertionHook.Invocations`| Count of hook executions| `ConfigurationName` +`PreManifestInsertionHook.Errors`| Count of hook errors| `ConfigurationName` +`PreManifestInsertionHook.Latency`| Hook execution time (ms)| `ConfigurationName` @@ -53,0 +60,8 @@ Event type| Default / Opt-in| Log group| Description +`POST_ADS_RESPONSE_HOOK_SUMMARY`| Opt-in| ADS Interaction Log| Hook execution summary (success/error) +`POST_ADS_RESPONSE_HOOK_ERROR`| Default| ADS Interaction Log| Hook failure with errorType and cause +`POST_ADS_RESPONSE_FUNCTION_COMPLETED`| Opt-in| ADS Interaction Log| Individual function completed with input/output +`POST_ADS_RESPONSE_FUNCTION_ERROR`| Default| ADS Interaction Log| Individual function failure +`PRE_MANIFEST_INSERTION_HOOK_SUMMARY`| Opt-in| ADS Interaction Log| Hook execution summary (success/error) +`PRE_MANIFEST_INSERTION_HOOK_ERROR`| Default| ADS Interaction Log| Hook failure with errorType and cause +`PRE_MANIFEST_INSERTION_FUNCTION_COMPLETED`| Opt-in| ADS Interaction Log| Individual function completed with input/output +`PRE_MANIFEST_INSERTION_FUNCTION_ERROR`| Default| ADS Interaction Log| Individual function failure @@ -115 +129 @@ This means the expression has too many levels of nesting for MediaTailor to proc -**Cause:** The expression calls a JSONata function that is not in the allowed list of 38 functions. Common examples include `$filter`, `$reduce`, `$eval`, `$split`, and `$join`. +**Cause:** The expression calls a JSONata function that is not in the allowed list of 44 functions. Common examples include `$eval`, `$assert`, `$error`, `$sift`. @@ -117 +131 @@ This means the expression has too many levels of nesting for MediaTailor to proc -**Fix:** Check the `cause` field for the blocked function name. Replace it with an allowed alternative. See [JSONata expression reference](./monetization-functions-jsonata.html) for the full list of 38 allowed functions. +**Fix:** Check the `cause` field for the blocked function name. Replace it with an allowed alternative. See [JSONata expression reference](./monetization-functions-jsonata.html) for the full list of 44 allowed functions. @@ -194,0 +209,28 @@ Check the `cause` field in the error log event — it identifies which field or +### Ad list change has no effect + +**Symptom:** Your function runs without errors at `POST_ADS_RESPONSE` or `PRE_MANIFEST_INSERTION`, but the ads in the stream are unchanged. A filter, reorder, or modification appears to be ignored. + +**Possible causes:** + +Cause| How to identify| Fix +---|---|--- +The filter expression produced zero or one result without array coercion, so the output key was omitted or misapplied. | The expression is a predicate filter such as `adsResponse.ads[adSystem != 'BLOCKED']` without a trailing `[]` or an enclosing array constructor. With one match it produces a single object; with zero matches it produces no value, and the output key is omitted, which the system treats as "no change". | Always coerce filter results to an array: `adsResponse.ads[adSystem != 'BLOCKED'][]` or `[adsResponse.ads[predicate]]`. +The ad break is not modifiable (`PRE_MANIFEST_INSERTION`). | The ad break's `mutable` input field is `false`. Modifications to these ad breaks are discarded. | Check `mutable` in your expression and only modify ad breaks where it is `true`. +The hook was skipped because the shared hook budget was exhausted or the input exceeded the size limit. | No `HOOK_SUMMARY` event for the hook in the ADS interaction log for that request. | Reduce time spent in earlier hooks, or reduce input size. See [Limits](./monetization-functions-limits.html). + +To confirm what your function actually returned, opt in to the `FUNCTION_COMPLETED` event types for the hook and inspect the function output in the ADS interaction log. + +### Injected ad doesn't appear in the manifest + +**Symptom:** Your `PRE_MANIFEST_INSERTION` function returns an injected ad and completes successfully, but the ad is not in the rendered manifest. + +Injection checks run after your function returns, so the function's log events report success even when an injection is dropped. Check the following causes in order: + +Cause| Fix +---|--- +The `creativeUrl` creative is not yet transcoded. MediaTailor drops the injection for the current ad break rather than waiting, but the attempt initiates transcoding. | Injecting the same URL into a later ad break succeeds after transcoding completes. For an immediate insertion, use a creative MediaTailor has already transcoded (a creative from a previous ad break, or a `skippedAds[].creativeUrl` value whose `reason` is not transcode-related), or inject by `vastAdId` with a `VAST_REQUEST` function in the same chain so MediaTailor handles media selection and transcode registration. +The entry has neither a usable `creativeUrl` nor a `vastAdId` that matches an ad parsed by a `VAST_REQUEST` call in the same hook invocation. | Call `VAST_REQUEST` in the same function chain as the injection, and inject using the parsed ad's `adId` value as `vastAdId`. +The invocation exceeded the injection limit of 10 ads. | Injections beyond the limit are dropped. Reduce the number of injected ads per invocation. +The target ad break is not modifiable (`mutable: false`). | Only inject into ad breaks where `mutable` is `true`. +The injected ad's renditions don't match the stream's variants, or the added duration overflows the ad break. | Injected ads go through the same variant matching and fill policy as ads from the ADS. Verify the creative's renditions match the stream, and keep total ad duration within the ad break. + @@ -201 +243 @@ To use the Amazon Web Services Documentation, Javascript must be enabled. Please -Example 2: A/B traffic split +Example 5: Origin audience routing