Log files provide granular data for various types of events. Once log data is collected and aggregated into log files, they are then delivered to your Amazon S3 bucket.
Ad log data is delivered separately from the log events discussed in this article. Learn more.
Alternatively, use reports on encoding, storage, and playback to understand how your bill was calculated and to gain insight into how your content was consumed.
Key information
-
If log data cannot be delivered (e.g., invalid credentials), we will send you an email notification and attempt to upload them again at a later time. Please disable log pushing or fix the access credentials as soon as possible.Email notifications are not sent more than once per 24 hour period.
-
Undelivered log files may be deleted after 14 days. Once a log file is erased, the data is lost and the associated events cannot be recovered.
-
Upon successfully delivering a log file, it will be erased from our system and cannot be regenerated.
-
Log data may contain sensitive information about your viewers (e.g., a viewer’s IP address). Although it is possible to obtain this information via an in-house media platform, you should protect the privacy of your users by treating all log data as confidential information.
-
Configure your S3 bucket to be private. You may not configure log delivery to a public S3 bucket.
-
Playback session IDs are generated by our system when a user begins playing encrypted content. Each session persists until the user closes their web browser / device playback environment or until the session is inactive for a long time period. This means that a single session may represent the playback of multiple assets and/or channels.
Enabling Log Delivery
Log data is pushed from our system to your Amazon S3 bucket. This requires that you provide the following information from the Log Pushing page (login required).
From the main menu, navigate to Settings > Log Pushing.
| Option | Description |
|---|---|
| AWS Access Key | Specify an Amazon access key ID for a dedicated user account that only has write permissions to the desired AWS S3 bucket. |
| AWS Secret Access Key | Specify an Amazon secret access key for a dedicated user account that only has write permissions to the desired AWS S3 bucket. |
| S3 Bucket Name | Specify the name of the private S3 bucket to which logs will be delivered. |
| Key Prefix | Specify the virtual log file storage location and/or a prefix that will be added to each object delivered to your bucket. |
Key information
-
Log delivery requires an Amazon S3 bucket. You may either use an existing private S3 bucket or create a new one via the AWS Management Console.Learn more about Getting Started with Amazon Simple Storage Service.
-
Do not send us credentials for an administrator account. Instead, you should create a dedicated user account that only has write permissions to the S3 bucket.Use the AWS Management Console to create user credentials and to verify that the user is authorized to create and upload objects.Learn more about AWS Identity and Access Management.
-
Log delivery is only allowed to a private S3 bucket.Use of a public S3 bucket may be cause for account termination.
-
Once enabled, logs will be delivered immediately and will continue to be delivered until it is disabled. Expect many small log files per day, since they are continuously generated.Logs are not delivered in sequential order. Rather, they are delivered as soon as they are processed.
Log Files
Log files are gzip-compressed plain text files with unique file names.
File Naming Convention
The naming convention for log files includes a prefix that categorizes objects by hour and then by event type.
Although the file extension is csv, fields are tab-separated.
Syntax
version=###/ exec_dt=YYYYMMDDhh/event_type=Event Type/part-Count-UUID.c000.csv.gzThe above date is only loosely tied to the data contained within a log file. Do not assume that all of the events contained within a log file occurred on that date.
Example
version=001/exec_dt=2023010810/event_type=slice_played/part-00000-3608d733-e96c-4575-8784-41154246e830.c000.csv.gzIn this example, a file called
part-00000-3608d733-e96c-4575-8784-41154246e830.c000.csv.gz will be stored in the following virtual directory:
version=001/exec_dt=2023010810/event_type=slice_played.Log Data
Key information
-
Events are reported below the format version and commented lines. Each line represents a single event.
-
Each line is composed of tab-separated values.
-
Empty values are represented by -.
-
The first 3 fields in every line are:
Name Description Date Identifies the date (UTC) on which the event occurred.
Syntax:YYYY-MM-DDTime Identifies the approximate time (UTC) at which the event occurred. An approximate time is reported due to latency in log collection and processing.
Syntax:hh:mm:ssEvent name Identifies the type of event. Learn more. -
Log entries are not guaranteed to be listed in sequential order. However, they are typically aggregated within a few minutes of each other.
-
The set of fields that will be reported after the initial 3 fields varies by event type. Learn more.
Sample Log File
12020-03-10 16:48:11 slice_played 24089701c7894902aebc3f1bd209ae2e 103 - - Roku/DVP-9.20 (519.20E04806A) - - 2b9fa9bd64804331b8da74c054b3cd67 - - - 0.8343682004336305 Spirit Games - - -232020-03-10 16:52:58 slice_played 080ca7672c1043599818cd823cb7e144 252 - - Roku/DVP-9.20 (289.20E04804A) - - 60614f69a767462aabe6152611d73aa1 - - - 0.636021907119814 My Fiancé - - -
Log Events
This section details log events and their fields.
Certain events support custom log fields. Each event type indicates the set of objects from which custom log fields may be added.
ad_beacon_sent
Indicates that an event beacon was sent to an ad server.
| Field | Description |
|---|---|
| group ID | Indicates an ID that identifies multiple URLs that correspond to a single event. For example, multiple impressions may be sent to various ad servers (e.g., Google Ad Manager, FreeWheel) for a single ad. |
| session ID | Indicates a unique playback session ID. Learn more about this playback session (session_created). |
| ad asset ID | Indicates the asset ID corresponding to the ad that was played. Value for non-ads (e.g., slot impression): - |
| event description | Indicates the type of event. Valid values are:videoview | slotimpression | defaultimpression | start | firstquartile | midpoint | thirdquartile | complete |
| ad break position | Indicates the zero-based position of the ad break. Syntax: [pre | mid | post].{Position}Example: The following sample value identifies the second mid-roll ad: mid.1 |
| ad index in break/pod | Indicates the zero-based index for the ad in the ad break / ad pod. For example, 1 indicates the second position in the ad break.Return value for events without ad breaks: -1 |
| ad ID | Indicates the ad ID provided by the ad server. FreeWheel defines this ID via ads/ad@adId. Default value (no ad ID): - |
| creative ID (FreeWheel only) | Indicates the creative ID returned by FreeWheel via ad/creatives/creative@creativeId. Default value (no creative ID): - |
| url | Indicates the event’s URL. |
| HTTP Status | Indicates the HTTP status code for the response from the ad server. |
ad_request_error
Indicates that an error occurred when making an HTTP request to the ad server.
| Field | Description |
|---|---|
| session ID | Indicates a unique playback session ID. Learn more about this playback session (session_created). |
| asset ID | Indicates the asset ID corresponding to the asset that was played. |
| ad break position | Indicates the zero-based position of the ad break. Syntax: [pre | mid | post] {Position}Example: The following sample value identifies the second mid-roll ad: mid.1 |
| ad request data | Returns either of the following:
|
| error description | Indicates the description or error event generated by the exception. |
| slicer build type | Provides the type and operating system for the Slicer that processed the requested content. Example: slicer_linux_64 |
| channel ID | Indicates a channel ID when an ad was requested during the playback of a live channel. Default value: - |
| event ID | Indicates an event ID when an ad was requested during the playback of a live event. Default value: - |
asset_deleted
Indicates that an asset was deleted.
| Field | Description |
|---|---|
| asset ID | Indicates the asset ID corresponding to the asset that was deleted. |
| cause | Indicates the reason why the asset was deleted. For example, an asset may be manually deleted, automatically deleted due to an auto-expiration policy, or automatically deleted because an error occurred during the slicing job. |
asset_play_started
Indicates that a viewer initiated the playback of live or VOD content.
| Field | Description |
|---|---|
| asset ID | Indicates the asset ID corresponding to the asset that was played. |
| user IP | Indicates the IP address of the playback device. |
| player user agent | Indicates the player’s user agent as reported by the User-Agent request header. |
| player referrer URL | Indicates the referrer as reported by the Referer request header. |
| channel ID | Indicates a channel ID if a live channel was played. Default value: - |
| asset is ad | Indicates whether the asset was an ad. Valid values are:
|
| euid | Indicates the external user ID provided in the playback URL. Default value: - |
| session ID | Indicates a unique playback session ID. Learn more about this playback session (session_created). |
| playing owner ID | Identifies the owner of shared content by user ID. Return value for your content: - If your user ID is returned by this field, then your content was played from another account (e.g., an ad or a shared library). |
| event ID | Indicates an event ID if a live event was played. Default value: - |
| beam_description | Enhanced Logs Only Indicates the description for an asset, live channel, or live event. |
| beam_external_id | Enhanced Logs Only Indicates the external ID assigned to an asset, live channel, or live event. |
| time_created_as_epoch | Enhanced Logs Only Indicates the timestamp, in Unix time (milliseconds), that an asset, live channel, or live event was created. |
| beam_duration | Enhanced Logs Only Indicates the duration for an asset, live channel, or live event. |
Fields marked as
Enhanced Logs Only will only be included when you have enabled enhanced logs. If you previously enabled custom log fields for the legacy version of log file delivery, then enhanced logs will be automatically enabled. Otherwise, please contact our technical support.channel_deleted
Indicates that the live channel was deleted.
| Field | Description |
|---|---|
| channel ID | Identifies the live channel that was deleted by its channel ID. |
| cause | Identifies the user that deleted the channel by their user ID. |
channel_ping
Indicates that the viewer continued to watch the live channel. This event, which is triggered every 10 minutes during the playback of a live channel, allows us to estimate simultaneous viewers during live playback.
Time is divided into ten-minute intervals that are known as buckets. During live playback, a single
channel_ping event is triggered once per bucket. Each bucket is assigned a unique number starting from 0. Bucket 0 refers to the Unix epoch (00:00:00 on January 1, 1970 UTC), bucket 1 starts 10 minutes after that, and so on.| Field | Description |
|---|---|
| channel ID | Identifies a live channel by its channel ID. |
| asset ID | Indicates the asset ID corresponding to the asset that was played. |
| bucket number | Identifies the number assigned to the bucket during which playback occurred. |
| user IP | Indicates the IP address of the playback device. |
| player user agent | Indicates the player’s user agent as reported by the User-Agent request header. |
| player referrer URL | Indicates the referrer as reported by the Referer request header. |
| euid | Indicates the external user ID provided in the playback URL. Default value: - |
| session ID | Indicates a unique playback session ID. Learn more about this playback session (session_created). |
channel_play_started
Indicates that a viewer initiated the playback of a live channel.
| Field | Description |
|---|---|
| user IP | Indicates the IP address of the playback device. |
| player user agent | Indicates the player’s user agent as reported by the User-Agent request header. |
| player referrer URL | Indicates the referrer as reported by the Referer request header. |
| euid | Indicates the external user ID provided in the playback URL. Default value: - |
| session ID | Indicates a unique playback session ID. Learn more about this playback session (session_created). |
drm_error
Indicates that a DRM-related error occurred. For example, a request from a player that uses a deprecated Content Decryption Module (CDM) will generate this type of error.
| Field | Description |
|---|---|
| beam ID | Indicates the asset ID corresponding to the asset, live channel, or live event that triggered the DRM error. |
| drm_type | Identifies the DRM solution. Valid values are: fairplay | widevine | playready |
| event_error_message | Indicates the DRM error message. |
An error log event is generated for errors that are unrelated to DRM.
drm_key_read
Indicates that a DRM key was read. This event occurs when a player requests a DRM license.
| Field | Description |
|---|---|
| timestamp | Indicates the timestamp, in Unix time (milliseconds), that the DRM key was read. |
| beam ID | Indicates the asset ID corresponding to the asset, live channel, or live event that triggered the DRM license request. |
| playing owner ID | Identifies the owner of shared content by user ID. Return value for your content: -If your user ID is returned by this field, then your content was played from another account (e.g., an ad or a shared library). |
| user IP | Indicates the IP address of the playback device. |
| player user agent | Indicates the player’s user agent as reported by the User-Agent request header. |
| slicer build type | Provides the type and operating system for the Slicer that processed the requested content. Example: slicer_linux_64 |
| beam description | Indicates the description for an asset, live channel, or live event. |
error
Indicates that an input error occurred. For example, the player may have requested an invalid playback URL.
| Field | Description |
|---|---|
| formatType | This field is reserved for future use. It currently returns 0. |
| subType | This field is reserved for future use. It currently returns web. |
| URL | Indicates the playback URL that caused the error. |
| user IP | Indicates the IP address of the playback device. |
| HTTP code | Indicates the status code (e.g., 404) for the response to the playback URL. |
| user agent | Indicates the player’s user agent as reported by the User-Agent request header. |
| message | Provides a short description of why the error occurred. |
event_copied
Indicates that a live event was copied.
| Field | Description |
|---|---|
| event ID | Identifies a live event by its event ID. |
| cause | Indicates the user ID for the user that copied the live event. |
event_ping
Indicates that the viewer continued to watch the live event. This event, which is triggered every 10 minutes during the playback of a live event, allows us to estimate simultaneous viewers during live playback.
Time is divided into 10 minute intervals that are known as buckets. During live playback, a single
event_ping event is triggered once per bucket. Each bucket is assigned a unique number starting from 0. Bucket 0 refers to the Unix epoch (00:00:00 on January 1, 1970 UTC), bucket 1 starts 10 minutes after that, and so on.| Field | Description |
|---|---|
| event ID | Identifies a live event by its event ID. |
| asset ID | Indicates the asset ID corresponding to the asset that was played. |
| bucket number | Identifies the number assigned to the bucket during which playback occurred. |
| user IP | Indicates the IP address of the playback device. |
| player user agent | Indicates the player’s user agent as reported by the User-Agent request header. |
| player referrer URL | Indicates the referrer as reported by the Referer request header. |
| euid | Indicates the external user ID provided in the playback URL. Default value: - |
| session ID | Indicates a unique playback session ID. Learn more about this playback session (session_created). |
event_play_started
Indicates that a user started watching a live event.
| Field | Description |
|---|---|
| event ID | Identifies a live event by its event ID. |
| user IP | Indicates the IP address of the playback device. |
| player user agent | Indicates the player’s user agent as reported by the User-Agent request header. |
| player referrer URL | Indicates the referrer as reported by the Referer request header. |
| euid | Indicates the external user ID provided in the playback URL. Default value: - |
| session ID | Indicates a unique playback session ID. Learn more about this playback session (session_created). |
session_created
Indicates that a new playback session was created.
| Field | Description |
|---|---|
| session ID | Indicates a unique playback session ID. Learn more about this playback session (session_created). |
| content ID | Indicates a channel ID, asset ID, or event ID for the playback session. |
| content type | Indicates the type of content that was played, Valid values are: asset | channel | event |
| playing owner ID | Identifies the owner of shared content by user ID. Return value for your content: -If your user ID is returned by this field, then your content was played from another account (e.g., an ad or a shared library). |
| user agent | Indicates the player’s user agent as reported by the User-Agent request header. |
| euid | Indicates the external user ID provided in the playback URL. Default value: - |
| referer | Indicates the referrer as reported by the Referer request header. |
| user IP | Indicates the IP address of the playback device. |
slice_played
Indicates that a single temporal slice of media was delivered. Each slice represents approximately 4 seconds of media. The timestamp corresponds to time at which the slice was delivered to the player.
| Field | Description |
|---|---|
| asset ID | Indicates the asset ID corresponding to the asset that was played. |
| slice number | Identifies a slice using a zero-based number. |
| is live | Indicates whether the slice corresponds to a live channel or a live event. Valid values are:
|
| user IP | Indicates the IP address of the playback device. |
| player user agent | Indicates the player’s user agent as reported by the User-Agent request header. |
| player referrer URL | Indicates the referrer as reported by the Referer request header. |
| euid | Indicates the external user ID provided in the playback URL. Default value: - |
| session ID | Indicates a unique playback session ID. Learn more about this playback session (session_created). |
| playing owner ID | Identifies the owner of shared content by user ID. Return value for your content: -If your user ID is returned by this field, then your content was played from another account (e.g., an ad or a shared library). |
| channel ID | Indicates a channel ID when the slice was played in the context of a live channel. Default value: - |
| event ID | Indicates an event ID when the slice was played in the context of a live event. Default value: - |
| duration of content delivered | Indicates either the duration of the video segment that was delivered or the byte range corresponding to the duration of the requested content. |
| beam_description | Enhanced Logs Only Indicates the description for an asset, live channel, or live event. |
| beam_external_id | Enhanced Logs Only Indicates the external ID assigned to an asset, live channel, or live event. |
| time_created_as_epoch | Enhanced Logs Only Indicates the timestamp, in Unix time (milliseconds), that an asset, live channel, or live event was created. |
| beam_duration | Enhanced Logs Only Indicates the duration for an asset, live channel, or live event. |
| ray_letter | Identifies the quality of the ray corresponding to the current slice by its letter. |
Fields marked as
Enhanced Logs Only will only be included when you have enabled enhanced logs. If you previously enabled custom log fields for the legacy version of log file delivery, then enhanced logs will be automatically enabled. Otherwise, please contact technical support.slicing_began
Indicates that an asset was created due to the start of either a live or VOD slicing job.
| Field | Description |
|---|---|
| job type | Valid values are: live | vod |
| asset ID | Indicates the asset ID corresponding to the new asset. |
| external ID | Indicates the external ID corresponding to the new asset. Default value: - |
| channel ID | Indicates a channel ID if a live channel was played. Default value: - |
| description | Indicates the description assigned to the new asset. Default value: - |
| slicer build type | Provides the type and operating system for the Slicer that processed the requested content. Example: slicer_linux_64 |
| slicer version | Indicates the slicer’s version number. |
| event ID | Indicates an event ID if a live event was played. Default value: - |
slicing_ended
Indicates that the slicing job finished.
| Field | Description |
|---|---|
| asset ID | Indicates the asset ID corresponding to the last asset in the slicing job. |
| had errors | Indicates whether an error occurred. Valid values are:
|
| slices | Indicates the number of slices that were delivered for encoding. |
Format History
Log file format is tracked via version numbers defined within the prefix assigned to your log file. This version number is incremented whenever we add a new event type or field. Upon incrementing the log file version, we will deliver both versions for a limited time period. Take advantage of this window to update your code to process log data from the new virtual directory and to account for the new event type(s) and/or field(s).
Your code should either raise a proper error or ignore unknown event types and fields.
Format history is provided below.
| Version | Description |
|---|---|
| 001 | Initial release |