# Integrate MediaTailor with MediaPackage and CDN
AWS Elemental MediaTailor integrates with AWS Elemental MediaPackage to deliver personalized video ads through a content delivery network (CDN). MediaPackage is a just-in-time video packaging and origination service that prepares and protects your video content for delivery over the internet. It takes your live or on-demand video content and packages it into streaming formats like HLS and DASH, making it ready for viewers on various devices.
When you combine MediaPackage with MediaTailor and a CDN, you create a complete streaming workflow that delivers personalized ads at scale. The CDN distributes your content globally, reducing latency and improving viewer experience, while MediaTailor inserts targeted advertisements into your streams.
This topic focuses on the essential integration steps to get MediaTailor, MediaPackage, and your CDN working together. For advanced configuration options, troubleshooting, and monitoring guidance, see [Next steps](#emp-cdn-next-steps).
## Understanding the MediaPackage and CDN workflow
Before configuring your integration, it's important to understand how MediaPackage, MediaTailor, and your CDN work together:
1. **Content preparation**: MediaPackage receives your live or on-demand video content and packages it into streaming formats (HLS or DASH manifests and segments).
1. **Ad insertion**: MediaTailor requests manifests from MediaPackage, inserts personalized ads, and serves the modified manifests to viewers.
1. **Global distribution**: Your CDN caches and distributes both the content segments (from MediaPackage) and ad segments (from MediaTailor) to viewers worldwide.
1. **Viewer playback**: Video players request manifests through the CDN, which routes requests appropriately between MediaTailor (for manifests) and MediaPackage (for content segments).
This architecture provides several benefits:
+ **Scalability**: The CDN handles high viewer loads without impacting your origin servers
+ **Performance**: Content is delivered from edge locations closest to viewers
+ **Cost efficiency**: Reduced bandwidth costs through caching
+ **Reliability**: Multiple edge locations provide redundancy
## Prerequisites
Before you begin, ensure you have the following components configured:
1. **MediaPackage endpoint**: A configured MediaPackage endpoint that's receiving and packaging your video content. For setup instructions, see [Getting started with MediaPackage](https://docs.aws.amazon.com/mediapackage/latest/ug/getting-started.html) in the MediaPackage user guide.
1. **MediaTailor configuration**: A MediaTailor configuration that uses your MediaPackage endpoint as the content origin. For setup instructions, see [Integrating a content source for MediaTailor ad insertion](integrating-origin.md).
1. **CDN distribution**: A CDN distribution (such as CloudFront) configured to work with streaming media. For setup instructions, see [Creating a distribution](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/distribution-web-creating-console.html) in the CloudFront developer guide.
1. **Ad decision server**: A configured ad decision server that returns VAST or VMAP responses for ad insertion.
## Step 1: Configure essential CDN settings
Proper CDN configuration is critical for successful MediaPackage integration. Incorrect settings can cause playback failures, poor cache performance, and increased costs. Without the right cache policies and query parameter forwarding, your CDN might not deliver manifests correctly or might bypass caching entirely, leading to high origin server load and degraded viewer experience.
### Configure basic cache settings
Configuring basic caching is essential because MediaPackage uses specific cache-control headers to optimize content delivery. Without proper cache settings, your CDN might ignore these headers, leading to unnecessary origin requests and increased latency. Follow these steps to ensure optimal caching behavior:
To configure basic caching that works with MediaPackage:
1. Open your CloudFront distribution settings in the CloudFront console.
1. Select or create a cache policy for your MediaPackage origin.
1. Enable the "Origin Cache-Control Headers" option.
1. Allow MediaPackage to control caching behavior through its cache-control headers.
This basic configuration allows MediaPackage to set appropriate cache durations for different content types automatically. To implement advanced cache optimization with specific TTL values and performance tuning, complete this basic setup first, then continue to [Optimize CDN caching for MediaTailor and MediaPackage content delivery](cdn-emp-caching.md).
### Configure essential query parameters
Query parameter configuration is crucial for MediaPackage functionality. Your CDN must forward specific query parameters to enable features like time-shifted viewing and low-latency streaming. Incorrect query parameter settings can prevent these features from working and I'm concerned reduce cache efficiency. Follow these steps to configure query parameter forwarding:
To ensure your CDN forwards the required query parameters to MediaPackage:
1. In your CloudFront distribution settings, select or create a cache policy for manifest requests.
1. Under "Cache key settings," select "Include specified query strings."
1. Add the following essential query parameters:
+ `start` and `end` - For time-shifted viewing functionality. These parameters are passed through to MediaPackage to define specific content windows for startover and catch-up viewing
+ `_HLS_msn` and `_HLS_part` - For supporting LL-HLS playback requests
+ `m` - For capturing the modified ti/compame of the endpoint. MediaPackage responses always include the `?m=###` tag to capture the modified time of the endpoint. If content is already cached with a different value for this tag, CloudFront requests a new manifest instead of serving the cached version
+ `aws.manifestfilter` - For manifest filtering functionality. If you're using manifest filtering, this parameter must be included to configure the distribution to forward the `aws.manifestfilter` query string to the MediaPackage origin, which is required for the manifest filtering feature to work
1. Only include the query strings that MediaPackage uses. Including unnecessary query strings reduces cache efficiency by creating multiple cache variations for the same content.
These parameters enable basic MediaPackage functionality with your CDN. If you need to implement content filtering for different subscription tiers or device types, complete this basic query parameter setup first, then proceed to [Set up manifest filtering with MediaTailor, MediaPackage, and CDN](cdn-emp-manifest-filtering.md).
For information about how MediaTailor passes query parameters like `start` and `end` through to MediaPackage for time-shifted viewing, see [MediaTailor query parameter handling for origins](origin-query-parameters.md) in [MediaTailor manifest query parameters](manifest-query-parameters.md).
### Configure response timeout for LL-HLS
Timeout configuration is critical for low-latency HLS because LL-HLS uses a "blocking requests" mechanism where the CDN waits for new content segments. If your timeout is too short, requests will fail before MediaPackage can respond with new segments, causing playback interruptions and poor viewer experience. Configure appropriate timeouts to ensure smooth LL-HLS playback:
If you're using low-latency HLS, configure your CDN timeout settings:
1. In your CDN settings, locate the origin timeout configuration.
1. Set the response timeout value to at least three times your parts duration.
1. For example, if your parts duration is 0.3 seconds, set the timeout to at least 0.9 seconds.
This ensures the CDN waits long enough for MediaPackage to respond when using the Blocking Requests mechanism.
## Step 2: Verify your integration
Testing your integration is essential to ensure that all components work together correctly before your viewers experience issues. A failed integration can result in broken playback, missing ads, or poor performance. This verification process helps you identify and resolve issues in a controlled environment.
After configuring your CDN settings, verify that your integration is working correctly by testing the complete workflow from content request to ad insertion.
### Step 2.1: Test basic playback
Basic playback testing verifies that your CDN correctly handles manifest requests and forwards them to MediaTailor. This test helps identify configuration issues with cache policies, query parameter forwarding, and manifest handling. Follow these steps to test basic manifest delivery:
Test that your basic integration is working by requesting a manifest through your CDN:
1. Use a web browser or curl to request a manifest URL through your CDN.
1. Verify that the manifest loads successfully and contains both content and ad segments.
1. Check that content segment URLs in the manifest point to your CDN domain.
1. Confirm that ad segment URLs also point to your CDN domain.
If the manifest loads correctly and contains the expected URLs, your basic integration is working. For comprehensive testing methodologies and advanced validation procedures, see [Testing and validation for CDN and MediaTailor integrations](cdn-integration-testing.md). To set up comprehensive monitoring of your integration's performance and health, see [Monitor performance for MediaPackage, CDN, and MediaTailor integrations](cdn-emp-monitoring.md).
### Step 2.2: Test video playback
Video playback testing ensures that your complete integration works end-to-end, including ad insertion and content delivery through your CDN. This test verifies that both content segments and ad segments are properly cached and delivered, and that the viewer experience meets your quality standards. Follow these steps to test complete playback functionality:
Test that video playback works correctly with ads inserted:
1. Use a video player (such as Video.js or HLS.js) to play your content through the CDN.
1. Verify that the video plays smoothly without buffering issues.
1. Confirm that ads are inserted at the expected times during playback.
1. Check that both content and ad segments load from your CDN (not directly from origins).
If playback works smoothly with ads, your integration is functioning correctly. For comprehensive testing methodologies and advanced validation procedures, see [Testing and validation for CDN and MediaTailor integrations](cdn-integration-testing.md). If you experience any playback issues, buffering, or ad insertion problems, see [Troubleshoot MediaPackage, CDN, and MediaTailor integrations](cdn-emp-troubleshooting.md).
## Next steps
After completing the basic integration, you can implement advanced features and optimizations:
**Advanced CDN optimization**
For detailed cache optimization, TTL configuration, and performance tuning, see [Optimize CDN caching for MediaTailor and MediaPackage content delivery](cdn-emp-caching.md).
**Manifest filtering**
To implement content filtering for tiered services, device optimization, or access control, see [Set up manifest filtering with MediaTailor, MediaPackage, and CDN](cdn-emp-manifest-filtering.md).
**Troubleshooting**
If you encounter issues with your integration, see [Troubleshoot MediaPackage, CDN, and MediaTailor integrations](cdn-emp-troubleshooting.md).
**Performance monitoring**
To set up comprehensive monitoring and understand key performance metrics, see [Monitor performance for MediaPackage, CDN, and MediaTailor integrations](cdn-emp-monitoring.md).
# Set up manifest filtering with MediaTailor, MediaPackage, and CDN
AWS Elemental MediaTailor uses manifest filtering with AWS Elemental MediaPackage to customize which audio and video streams are included in manifests delivered to different viewers through a content delivery network (CDN). This is particularly useful for implementing tiered service offerings, device-specific optimizations, or content access controls.
This topic focuses specifically on implementing manifest filtering features. Before implementing manifest filtering, you must complete the basic content delivery network integration setup. If you haven't set up your basic MediaPackage and content delivery network integration yet, start with [Integrate MediaTailor with MediaPackage and CDN](mediapackage-integration.md).
## Manifest filtering capabilities
Before implementing manifest filtering, understand what you can accomplish with this feature:
### Core filtering capabilities
Manifest filtering provides several key capabilities that help you control content delivery:
+ Restrict viewer access to premium content (such as 4K HEVC)
+ Target specific device types with appropriate streams
+ Filter content based on audio sample rates, languages, or video codecs
+ Deliver different quality tiers to different subscribers
### Common use cases
These use cases demonstrate how manifest filtering can address specific business requirements:
**Subscription tiers**
Offer basic subscribers lower resolution streams while providing premium subscribers access to 4K content
Example: Basic tier limited to 720p, Premium tier gets up to 4K
**Device optimization**
Automatically serve appropriate streams based on device capabilities
Example: Mobile devices get lower bitrates, smart TVs get higher quality
**Bandwidth management**
Limit stream quality during peak usage periods to manage network costs
Example: Reduce maximum bitrate during high-traffic events
**Regional content**
Serve different audio languages or content variants based on viewer location
Example: Automatically filter for local language audio tracks
For more information about manifest filtering concepts, see [Manifest filtering](https://docs.aws.amazon.com/mediapackage/latest/ug/manifest-filtering.html) in the AWS Elemental MediaPackage user guide.
## Configure your CDN for manifest filtering
CDN configuration for manifest filtering is essential because your CDN must forward the `aws.manifestfilter` query parameter to MediaPackage for filtering to work. Without proper query string forwarding, filter parameters will be stripped by the CDN, and all viewers will receive unfiltered manifests regardless of their subscription tier or device capabilities. This configuration ensures that your filtering logic reaches MediaPackage and functions as intended.
To enable manifest filtering through your CDN, you need to configure query string forwarding:
1. In your CloudFront distribution, create or edit the cache behavior for manifest requests.
1. For **Cache policy,** create a new policy or edit an existing one.
1. Under **Cache key settings**, choose "Include specified query strings."
1. Add `aws.manifestfilter` to the list of allowed query strings.
1. If you're also using other MediaPackage features, add their query parameters:
+ `start` and `end` - For time-shifted viewing
+ `time_delay` - For time delay functionality
+ `_HLS_msn` and `_HLS_part` - For LL-HLS
For more information about creating distributions, see [Create a distribution](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/distribution-web-creating-console.html) in the Amazon CloudFront developer guide.
## Implement client-side filtering
Client-side implementation is where you define how your video players and applications request filtered content. This configuration determines what content each viewer receives based on their subscription level, device capabilities, or other criteria. Proper implementation ensures that viewers receive only the content they should have access to, while maintaining optimal CDN cache efficiency.
To implement manifest filtering in your video players and applications:
### How filtering works
The filtering process works as follows:
1. Your video player or application requests a manifest URL that includes filter parameters
1. The CDN forwards the request (including query parameters) to MediaTailor
1. MediaTailor passes the filter parameters to MediaPackage when requesting the origin manifest
1. MediaPackage applies the filters and returns a customized manifest containing only the variants that match your criteria
1. MediaTailor processes the filtered manifest for ad insertion and returns it to the player
### URL format for filtering
Understanding the correct URL format is critical for successful filtering implementation. Incorrect URL formatting will result in filtering parameters being ignored or causing HTTP errors. The URL structure must include filter parameters as query strings that your CDN forwards to MediaPackage. Follow these steps to implement proper URL formatting:
To implement manifest filtering in your video players:
1. Modify your player's manifest request URLs to include the appropriate filter parameters.
1. Use the following URL format with query parameters:
```
https://CloudFront-Domain/v1/master/MediaTailor-Config/index.m3u8?aws.manifestfilter=video_codec:h264;audio_language:en-US
```
1. When your player requests this URL, MediaTailor will pass these parameters to MediaPackage, resulting in a filtered manifest.
## Common filtering scenarios
Use these examples to implement common filtering scenarios:
**Device-specific content delivery**
To filter based on device capabilities, add this parameter to your manifest request:
```
aws.manifestfilter=video_codec:h264;audio_sample_rate:0-44100
```
This example limits content to H.264 video and audio with sample rates up to 44.1 kHz, suitable for mobile devices.
**Premium content restriction**
To limit access to high-bitrate content, add this parameter to your manifest request:
```
aws.manifestfilter=video_bitrate:0-9000000
```
This example restricts video bitrates to 9 Mbps or lower, suitable for basic subscription tiers.
**Language selection**
To filter for specific audio languages, add this parameter to your manifest request:
```
aws.manifestfilter=audio_language:fr,en-US,de
```
This example includes only French, US English, and German audio tracks.
**Resolution targeting**
To filter for specific video resolutions, add this parameter to your manifest request:
```
aws.manifestfilter=video_height:240-360,720-1080
```
This example includes video streams with heights between 240-360 pixels and 720-1080 pixels, excluding mid-range resolutions.
**Codec-based filtering**
To filter for specific video codecs, add this parameter to your manifest request:
```
aws.manifestfilter=video_codec:h264,h265
```
This example includes only H.264 and H.265 video streams, excluding other codecs.
## Special considerations and limitations
To avoid common issues when implementing manifest filtering:
### Technical limitations
+ For TS manifests, use audio rendition groups to avoid removing video streams that are multiplexed with filtered-out audio streams
+ In TS and CMAF manifests, audio sample rate and video bitrate are not easily visible in the manifest for verification
+ Request parameters appended to media playlists or segments will result in an HTTP 400 error
### Error conditions
+ If filtering results in an empty manifest (no streams meet the filter criteria), MediaPackage will return an HTTP 400 error
+ Conflicting filter configurations (endpoint filters \$1 query parameters) result in HTTP 404 errors
+ Invalid filter syntax or unsupported filter types result in HTTP 400 errors
### Performance considerations
+ Each unique filter combination creates a separate cache entry, potentially reducing cache efficiency
+ Complex filters with many criteria might impact manifest generation performance
+ Consider using endpoint-level filters for static filtering scenarios to improve cache performance
## Test your filtering implementation
Testing your manifest filtering implementation is crucial to ensure that viewers receive the correct content based on their access level and device capabilities. Failed filtering can result in viewers receiving incorrect quality levels, unsupported formats, or content they shouldn't have access to. Comprehensive testing helps identify and resolve these issues before they affect your viewers.
To verify that your manifest filtering is working correctly:
1. Request manifests with different filter parameters and verify the results
1. Check that filtered manifests contain only the expected streams
1. Test edge cases (empty results, invalid filters) to ensure proper error handling
1. Verify that your CDN is properly forwarding filter parameters
1. Test with different devices and players to ensure compatibility
For troubleshooting filtering issues, see *Troubleshoot MediaPackage CDN integration issues*.
If you encounter HTTP 400 errors, empty manifests, or filtering parameters that don't work as expected, see [Troubleshoot MediaPackage, CDN, and MediaTailor integrations](cdn-emp-troubleshooting.md) for specific manifest filtering troubleshooting guidance.
# Optimize CDN caching for MediaTailor and MediaPackage content delivery
AWS Elemental MediaTailor requires proper content delivery network (CDN) caching configuration for optimal performance when using AWS Elemental MediaPackage as your content origin. MediaPackage provides specific cache-control headers that tell your content delivery network how long to cache different types of content. Following these recommendations ensures smooth playback and efficient content delivery.
This topic focuses specifically on optimizing caching behavior to maximize performance and minimize costs. Before implementing advanced caching optimization, ensure you have completed the basic content delivery network integration setup. If you haven't set up your basic integration yet, start with [Integrate MediaTailor with MediaPackage and CDN](mediapackage-integration.md).
## MediaPackage cache-control headers
MediaPackage sets specific TTL values for different content types to optimize caching behavior:
**Multivariant playlists (HLS and LL-HLS)**
TTL: Half the duration of the media segments
Reason: These playlists change as new segments become available, so they need frequent updates
**Media playlists (regular HLS)**
TTL: Half the duration of the media segments
Reason: Similar to multivariant playlists, these update as content progresses
**Media playlists (LL-HLS)**
TTL: 1 second
Reason: Low-latency streaming requires very frequent updates
**TS media segments and init segments**
TTL: 1209600 seconds (14 days)
Reason: Media segments don't change once created, so they can be cached for extended periods
**CMAF media segments and initialization segments**
TTL: 1209600 seconds (14 days)
Reason: Like TS segments, these are immutable once created
For comprehensive TTL recommendations across all MediaTailor workflows and additional caching optimization strategies, see [Caching optimization for CDN and MediaTailor integrations](cdn-optimize-caching.md).
## Configure CDN cache policies
Proper cache policy configuration is essential for optimal performance and cost efficiency. Different types of content (manifests, segments, initialization files) have different caching requirements. Using separate cache behaviors allows you to optimize caching for each content type, improving cache hit ratios and reducing origin load. Without proper cache policies, you might experience unnecessary origin requests, increased costs, and poor playback performance.
To properly honor MediaPackage cache-control headers and optimize caching:
1. Open your CloudFront distribution settings in the CloudFront console.
1. Create separate cache behaviors for different content types:
+ Manifest requests (\$1.m3u8, \$1.mpd)
+ Media segments (\$1.ts, \$1.mp4, \$1.m4s)
+ Initialization segments
1. For each cache behavior, create or select a cache policy with these settings:
+ Enable "Origin Cache-Control Headers" option
+ Set "Origin request policy" to forward necessary headers
+ Configure query string forwarding based on content type
### Manifest cache behavior
For manifest requests (\$1.m3u8, \$1.mpd):
+ **Path pattern**: \$1.m3u8 and \$1.mpd
+ **Cache policy**: Honor origin cache-control headers
+ **Query strings**: Forward specific parameters (see [Optimize query string forwarding](#cdn-query-string-optimization))
+ **Headers**: Forward all headers (for minimum requirements, see [Required headers for MediaTailor CDN integration](cdn-configuration.md#cdn-required-headers))
### Media segment cache behavior
For media segments (\$1.ts, \$1.mp4, \$1.m4s):
+ **Path pattern**: \$1.ts, \$1.mp4, \$1.m4s
+ **Cache policy**: Honor origin cache-control headers (14-day TTL)
+ **Query strings**: None (segments don't use query parameters)
+ **Compression**: Enable for improved delivery performance
## Optimize query string forwarding
Query string optimization is critical for cache efficiency because unnecessary query parameters create multiple cache variations for the same content. Each unique query parameter combination creates a separate cache entry, which reduces cache hit ratios and increases origin requests. By forwarding only the query strings that MediaPackage actually uses, you maximize cache efficiency while maintaining full functionality.
Configure your CDN to forward only the query strings that MediaPackage uses, improving cache efficiency:
**Essential query strings**
`start` and `end` - For time-shifted viewing windows
`time_delay` - For applying time delay on manifest contents
`_HLS_msn`, `_HLS_m`, and `_HLS_part` - For LL-HLS playback requests
**Feature-specific query strings**
`aws.manifestfilter` - For [manifest filtering](cdn-emp-manifest-filtering.md)
**Important**
Do not include any other query strings in your cache key. MediaPackage ignores unrecognized parameters, and including them reduces cache efficiency by creating unnecessary cache variations.
## Performance optimization techniques
These optimizations are configured on your CDN (such as CloudFront), not in MediaPackage or MediaTailor. Implement these additional optimizations to maximize cache performance:
### Origin shield
Origin shield provides an additional caching layer between your CDN edge locations and MediaPackage endpoints. This reduces the number of requests that reach your MediaPackage endpoints, which can improve performance and reduce costs, especially during traffic spikes or when cache hit ratios are lower than optimal. Origin shield is particularly beneficial for live streaming where multiple edge locations might request the same content simultaneously.
Enable origin shield to reduce load on your MediaPackage endpoints:
1. In your CloudFront distribution, enable Origin Shield for your MediaPackage origin.
1. Select an origin shield region close to your MediaPackage endpoint.
1. This creates an additional caching layer that reduces requests to MediaPackage.
### Compression configuration
Enable compression for text-based responses:
+ Enable compression for manifest files (\$1.m3u8, \$1.mpd)
+ Do not compress media segments (already compressed)
+ Ensure all headers are forwarded to MediaPackage (for minimum requirements, see [Required headers for MediaTailor CDN integration](cdn-configuration.md#cdn-required-headers))
## Monitor cache performance
Track these key metrics to ensure optimal cache performance:
**Cache hit ratio**
Target: 90% or greater for media segments, 70% or greater for manifests
Low ratios might indicate incorrect TTL settings or unnecessary query parameters
**Origin request volume**
Monitor requests reaching MediaPackage endpoints
High volumes might indicate caching issues
**Cache key variations**
Review cache key patterns to identify unnecessary variations
Too many variations reduce cache efficiency
After implementing these cache optimizations, set up monitoring to track their effectiveness. For guidance on monitoring cache hit ratios, origin request patterns, and other key performance metrics, see [Monitor performance for MediaPackage, CDN, and MediaTailor integrations](cdn-emp-monitoring.md). If you observe poor cache performance or unexpected origin requests, see [Troubleshoot MediaPackage, CDN, and MediaTailor integrations](cdn-emp-troubleshooting.md) for troubleshooting steps.
# Monitor performance for MediaPackage, CDN, and MediaTailor integrations
AWS Elemental MediaTailor requires effective monitoring to maintain optimal performance of your AWS Elemental MediaPackage and content delivery network (CDN) integration. This topic provides guidance on key metrics to track, monitoring tools to use, and how to set up alerts for proactive issue detection.
Before setting up monitoring, ensure your basic integration is working correctly. If you haven't completed your basic content delivery network integration setup, start with [Integrate MediaTailor with MediaPackage and CDN](mediapackage-integration.md). If you need to troubleshoot issues identified through monitoring, see [CDN integration troubleshooting](cdn-emp-troubleshooting.md)..
## Key performance metrics
Monitor these essential metrics to ensure optimal performance of your MediaPackage and CDN integration:
### CDN performance metrics
For comprehensive CDN performance metrics including cache hit ratio targets, origin request volume monitoring, and response time benchmarks, see [Performance benchmarks for CDN and MediaTailor integrations](cdn-performance-benchmarks.md) in the CDN optimization guide.
Key EMP-specific considerations for CDN metrics:
**EMP cache-control headers**
**What to verify**: Ensure your CDN honors EMP's cache-control headers for optimal TTL behavior
**Expected behavior**: Different content types should have different cache durations based on EMP's headers
For detailed guidance on EMP cache optimization, see [Optimize CDN caching for MediaTailor and MediaPackage content delivery](cdn-emp-caching.md).
**Query parameter impact**
**What to monitor**: Track how EMP-specific query parameters affect cache efficiency
**Optimization target**: Ensure only necessary EMP query parameters are included in cache keys
**CDN response times**
**What to monitor**: Track response times for different content types (manifests vs. segments).
**Target values**:
+ Cached content: less than 100ms
+ Origin requests: less than 500ms
### MediaPackage performance metrics
**Error rates**
**What to monitor**: Monitor HTTP error rates from both your CDN and MediaPackage endpoints. Pay particular attention to 4xx errors, which might indicate configuration issues.
**Key error codes**:
+ 400 errors: Often related to manifest filtering issues
+ 404 errors: Might indicate routing or configuration problems
+ 504 errors: Timeout issues, especially with LL-HLS
**Request volume and patterns**
**What to monitor**: Track request patterns to MediaPackage endpoints to identify usage trends and capacity needs.
**Patterns to watch**:
+ Peak usage times
+ Geographic distribution of requests
+ Content type distribution (live vs. on-demand)
### Latency metrics
**End-to-end latency**
**What to monitor**: For LL-HLS implementations, monitor end-to-end latency from content ingest to viewer playback. High latency might indicate CDN configuration issues.
**Target values**:
+ LL-HLS: less than 3 seconds glass-to-glass latency
+ Regular HLS: less than 30 seconds
**Manifest generation time**
**What to monitor**: Time taken by MediaPackage to generate manifests, especially with filtering applied.
**Target values**: less than 200ms for manifest generation
## Monitoring tools and setup
Setting up comprehensive monitoring tools is essential for maintaining optimal performance and quickly identifying issues before they impact viewers. Without proper monitoring, performance degradation, cache inefficiencies, or integration problems might go unnoticed until viewers experience poor playback quality. The right monitoring setup provides visibility into all aspects of your MediaPackage and CDN integration.
Use these AWS services and tools to monitor your MediaPackage and CDN integration:
### Amazon CloudWatch
Amazon CloudWatch provides the foundation for monitoring your MediaPackage and CDN integration by collecting and storing metrics from both services. Proper CloudWatch configuration ensures you have the data needed to identify performance trends, troubleshoot issues, and optimize your integration. Without CloudWatch metrics, you'll lack visibility into system performance and might not detect issues until they become critical.
Set up CloudWatch monitoring for comprehensive metrics collection:
1. **MediaPackage metrics**: Enable CloudWatch metrics for your MediaPackage endpoints to track request volumes, error rates, and response times.
1. **CDN metrics**: Configure CloudWatch to collect CloudFront metrics including cache hit ratios, origin request counts, and error rates.
1. **Custom metrics**: Create custom metrics for business-specific KPIs like viewer engagement or content popularity.
### CloudWatch dashboards
Create comprehensive dashboards to visualize your metrics:
1. **Overview dashboard**: High-level metrics showing overall system health
1. **CDN performance dashboard**: Detailed CDN metrics including cache performance and geographic distribution
1. **MediaPackage performance dashboard**: MediaPackage-specific metrics including request patterns and error rates
1. **Latency dashboard**: End-to-end latency metrics for different content types and regions
### Log analysis
Set up log analysis for detailed troubleshooting:
1. **CDN access logs**: Enable and analyze CDN access logs to understand request patterns and identify issues
1. **MediaPackage CloudWatch logs**: Monitor MediaPackage logs for errors and performance issues
1. **Log aggregation**: Use Amazon CloudWatch Logs Insights or third-party tools to analyze log patterns
## Set up alerts and notifications
Alert configuration is crucial for proactive issue detection and resolution. Without proper alerts, issues might go unnoticed until they significantly impact viewer experience or cause service disruptions. Well-configured alerts help you identify and address problems before they affect your viewers, and ensure your team is notified of critical issues that require immediate attention.
Configure proactive alerts to identify issues before they impact viewers:
### Critical alerts
Set up immediate alerts for critical issues:
+ **High error rates**: Alert when 4xx or 5xx error rates exceed 5% over a 5-minute period
+ **Cache hit ratio drops**: Alert when cache hit ratio falls below 70% for manifests or 85% for segments
+ **High latency**: Alert when end-to-end latency exceeds target thresholds
+ **Origin request spikes**: Alert when origin requests increase by more than 50% compared to baseline
### Warning alerts
Set up warning alerts for trends that might indicate developing issues:
+ **Gradual performance degradation**: Alert when response times increase by 20% over a 30-minute period
+ **Cache efficiency trends**: Alert when cache hit ratios show declining trends over time
+ **Unusual traffic patterns**: Alert for unexpected changes in request volume or geographic distribution
## Use monitoring data for optimization
Leverage monitoring data to continuously improve performance:
### Regular performance reviews
1. **Weekly reviews**: Analyze weekly performance trends and identify optimization opportunities
1. **Monthly capacity planning**: Use traffic patterns to plan for capacity needs and CDN optimization
1. **Quarterly architecture reviews**: Evaluate overall architecture efficiency and identify areas for improvement
### Common optimization actions
Based on monitoring data, consider these optimization actions:
+ **Cache policy adjustments**: Modify TTL values based on actual content update patterns. For detailed TTL optimization guidance, see [Caching optimization for CDN and MediaTailor integrations](cdn-optimize-caching.md).
+ **Geographic optimization**: Add CDN edge locations in regions with high traffic
+ **Query parameter optimization**: Remove unnecessary query parameters that fragment cache
+ **Origin shield configuration**: Implement origin shield in regions with high origin request volumes
For detailed monitoring guidance specific to MediaPackage, see [Monitoring MediaPackage](https://docs.aws.amazon.com/mediapackage/latest/ug/monitoring.html) in the MediaPackage user guide.
# Troubleshoot MediaPackage, CDN, and MediaTailor integrations
AWS Elemental MediaTailor integration with AWS Elemental MediaPackage and content delivery network (CDN) can encounter common issues that affect playback, caching, or other integration functionality. Use this guide when you encounter playback problems, caching issues, or other integration-related errors.
For comprehensive CDN troubleshooting guidance including universal cache performance issues, HTTP error resolution, testing procedures, and diagnostic techniques that apply to all MediaTailor implementations, see [Troubleshoot CDN integration](cdn-troubleshooting.md). This section focuses on MediaPackage specific troubleshooting requirements.
Before troubleshooting, ensure you've completed the basic integration setup correctly. If you haven't set up your integration yet or need to review the setup steps, see [Integrate MediaTailor with MediaPackage and CDN](mediapackage-integration.md). For guidance on optimizing cache performance after resolving issues, see [CDN caching](cdn-emp-caching.md).
## Manifest filtering errors
Issues with MediaPackage manifest filtering functionality, based on documented error conditions:
**HTTP 400 errors with manifest filtering**
**Symptoms**: Requests with `aws.manifestfilter` parameters return HTTP 400 Bad Request
**Validated causes (from AWS documentation)**:
+ Filter criteria result in an empty manifest (no streams match the filter conditions)
+ Invalid filter parameter names or values
+ Malformed query string syntax
+ Duplicate or repeated filter parameters
+ Filter parameter string exceeds 1024 characters
+ Query parameters applied to media playlists or segments (not supported)
**Solutions**:
1. Review your filter parameters to ensure they match available content streams. If filtering results in no matching streams, MediaPackage returns HTTP 400.
1. Validate filter syntax against supported parameter names and value formats.
1. Check for duplicate parameters in your query string.
1. Ensure filter parameters are only applied to multivariant playlists, not to media playlists or segments.
1. Verify that your total parameter string is under 1024 characters.
**Reference**: [AWS Elemental MediaPackage manifest filtering error conditions](https://docs.aws.amazon.com/mediapackage/latest/userguide/error-conditions-and-handling.html)
**Manifest filtering not working (HTTP 200 but no filtering applied)**
**Symptoms**: Requests return HTTP 200 but manifest contains all streams instead of filtered subset
**Possible causes**:
+ CDN not forwarding `aws.manifestfilter` query parameter to MediaPackage
+ Filter parameter not found in available streams (returns unfiltered manifest with HTTP 200)
**Solutions**:
1. Verify that your CDN cache policy includes `aws.manifestfilter` in the list of forwarded query strings.
1. Test filter parameters directly against MediaPackage endpoints (bypassing CDN) to verify they work as expected.
1. Check that filter values match the actual characteristics of your content streams.
**Reference**: [AWS Elemental MediaPackage manifest filtering error conditions](https://docs.aws.amazon.com/mediapackage/latest/userguide/error-conditions-and-handling.html)
## Diagnostic procedures
Systematic diagnostic procedures help you identify the root cause of integration issues quickly and efficiently. Following a structured approach prevents wasted time on incorrect assumptions and ensures you address the actual problem rather than symptoms. These evidence-based diagnostic steps are designed to isolate issues and guide you to the appropriate solution.
Follow these evidence-based diagnostic steps to identify issues:
### Analyze cache performance
Cache performance analysis is crucial for EMP integrations because poor cache efficiency leads to increased origin load, higher costs, and potential playback issues.
For comprehensive cache performance troubleshooting including cache hit ratio analysis, cache key optimization, and systematic diagnostic steps, see [CDN cache performance issues](diagnose-performance-issues.md#cache-performance-troubleshooting) in the main CDN troubleshooting guide.
EMP-specific cache considerations:
+ **EMP cache-control headers**: Verify that your CDN honors EMP's cache-control headers rather than overriding them
+ **EMP query parameters**: Ensure only necessary EMP query parameters are included in cache keys
+ **EMP TTL behavior**: Confirm different EMP content types have appropriate cache durations
For detailed guidance on optimizing EMP cache policies and TTL settings, see [Optimize CDN caching for MediaTailor and MediaPackage content delivery](cdn-emp-caching.md).
### Validate manifest filtering configuration
Manifest filtering validation is essential because filtering issues can result in viewers receiving incorrect content, unsupported formats, or content they shouldn't have access to. Systematic testing helps identify whether issues are related to CDN configuration, filter parameter syntax, or content availability.
Test manifest filtering functionality systematically:
1. Test filter parameters directly against MediaPackage endpoints (bypassing CDN) to verify they work correctly.
1. Compare filtered and unfiltered manifests to confirm expected streams are included/excluded.
1. Verify that your CDN cache policy forwards the `aws.manifestfilter` query parameter.
1. Check for HTTP 400 errors and match them against the documented error conditions.
If you need to implement or modify manifest filtering after resolving issues, see [Set up manifest filtering with MediaTailor, MediaPackage, and CDN](cdn-emp-manifest-filtering.md) for complete setup guidance.
### Validate query parameter configuration
Ensure your CDN forwards only the required query parameters:
1. Review your CDN cache policy to confirm it includes only AWS recommended parameters:
+ `aws.manifestfilter` - for manifest filtering
+ `aws.manifestsettings` - for time-shifted viewing
+ `_HLS_msn` and `_HLS_part` - for LL-HLS support
1. Remove any other query parameters from your cache key, as MediaPackage ignores them and they reduce cache efficiency.
**Reference**: [Working with AWS Elemental MediaPackage and CDNs](https://docs.aws.amazon.com/mediapackage/latest/userguide/cdns.html)
## Error code reference
Reference for documented error conditions and their causes:
**HTTP 400 Bad Request (Manifest Filtering)**
**Documented causes**:
+ Application of filter results in empty manifest
+ Invalid parameter names or values
+ Malformed query string syntax
+ Duplicate filter parameters
+ Parameter string exceeds 1024 characters
+ Query parameters on media playlists or segments
**Reference**: [MediaPackage manifest filtering error conditions](https://docs.aws.amazon.com/mediapackage/latest/userguide/error-conditions-and-handling.html)
**HTTP 200 OK (No Filtering Applied)**
**Documented causes**:
+ Filter parameter not found in available streams (returns unfiltered manifest)
+ Only subtitle streams present after filtering (returns unfiltered manifest)
**Reference**: [MediaPackage manifest filtering error conditions](https://docs.aws.amazon.com/mediapackage/latest/userguide/error-conditions-and-handling.html)
## Additional troubleshooting resources
For issues not covered in this topic, consult these official AWS resources:
+ [Previewing a manifest from AWS Elemental MediaPackage](https://docs.aws.amazon.com/mediapackage/latest/userguide/endpoints-preview.html) - Use manifest preview to troubleshoot content packaging issues
+ [Increase CloudFront cache hit ratio](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/cache-hit-ratio.html) - Comprehensive guide to CDN cache optimization
+ [Manifest filtering](https://docs.aws.amazon.com/mediapackage/latest/userguide/manifest-filtering.html) - Complete guide to MediaPackage filtering functionality