Log files provide granular data for various types of eventsAn event identifies an action that took place during playback, ad requests, or the administration of live channels, live events, and assets. An example of an event is session_created which occurs whenever a new playback session is initiated. . 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.
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 :
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 (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.
Log delivery is only allowed to a private S3 bucket.
Use of a public S3 bucket may be cause for account termination.
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 are gzip-compressed plain text files with unique file names.
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:
The 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:
In this example, a file called part-00000-3608d733-e96c-4575-8784-41154246e830.c000.csv.gz will be stored in the following virtual directory:
Key information:
The first 3 fields in every line are:
Name | Description |
---|---|
Date |
Identifies the date (UTC) on which the event occurred. Syntax: YYYY-MM-DD
|
Time |
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:ss
|
Event name |
Identifies the type of event. |
The set of fields that will be reported after the initial 3 fields varies by event type.
2020-03-10 16:48:11 slice_played 24089701c7894902aebc3f1bd209ae2e 103 - - Roku/DVP-9.20 (519.20E04806A) - - 2b9fa9bd64804331b8da74c054b3cd67 - - - 0.8343682004336305 Spirit Games - - -
2020-03-10 16:52:58 slice_played 080ca7672c1043599818cd823cb7e144 252 - - Roku/DVP-9.20 (289.20E04804A) - - 60614f69a767462aabe6152611d73aa1 - - - 0.636021907119814 My Fiancé - - -
Learn about the following 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.
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, and Verizon Media Ad Platform Video SSP) for a single ad. |
session ID |
Indicates a unique playback session ID. |
ad asset ID |
Indicates the asset IDThis unique ID identifies an asset. View this ID by navigating to the Content tab, selecting the desired asset, and then viewing the GUID option from the Details tab. 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. |
Indicates that an error occurred when making an HTTP request to the ad server.
Field | Description |
---|---|
session ID |
Indicates a unique playback session ID. |
asset ID |
Indicates the asset IDThis unique ID identifies an asset. View this ID by navigating to the Content tab, selecting the desired asset, and then viewing the GUID option from the Details tab. 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 IDThis unique ID identifies a live channel. View this ID by navigating to the Live Channels tab, selecting the desired live channel, and then viewing the GUID option from the Details tab. when an ad was requested during the playback of a live channel. Default value: -
|
event ID |
Indicates an event IDThis unique ID identifies a live event. View this ID by navigating to the Live Events tab, selecting the desired live event, and then viewing the GUID option from the right-hand pane of the Details tab. when an ad was requested during the playback of a live event. Default value: -
|
Indicates that an asset was deleted.
Field | Description |
---|---|
asset ID |
Indicates the asset IDThis unique ID identifies an asset. View this ID by navigating to the Content tab, selecting the desired asset, and then viewing the GUID option from the Details tab. 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. |
Indicates that a viewer initiated the playback of live or VOD content.
Field | Description |
---|---|
asset ID |
Indicates the asset IDThis unique ID identifies an asset. View this ID by navigating to the Content tab, selecting the desired asset, and then viewing the GUID option from the Details tab. 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 IDThis unique ID identifies a live channel. View this ID by navigating to the Live Channels tab, selecting the desired live channel, and then viewing the GUID option from the Details tab. 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. |
playing owner ID |
Identifies the owner of shared content by user IDA user ID uniquely identifies a user account via an alpanumeric system-defined 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 IDThis unique ID identifies a live event. View this ID by navigating to the Live Events tab, selecting the desired live event, and then viewing the GUID option from the right-hand pane of the Details tab. 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.
Indicates that the live channel was deleted.
Field | Description |
---|---|
channel ID |
Identifies the live channel that was deleted by its channel IDThis unique ID identifies a live channel. View this ID by navigating to the Live Channels tab, selecting the desired live channel, and then viewing the GUID option from the Details tab.. |
cause |
Identifies the user that deleted the channel by their user IDA user ID uniquely identifies a user account via an alpanumeric system-defined ID.. |
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 10 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 IDThis unique ID identifies a live channel. View this ID by navigating to the Live Channels tab, selecting the desired live channel, and then viewing the GUID option from the Details tab.. |
asset ID |
Indicates the asset IDThis unique ID identifies an asset. View this ID by navigating to the Content tab, selecting the desired asset, and then viewing the GUID option from the Details tab. 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. |
Indicates that a viewer initiated the playback of a live channel.
Field | Description |
---|---|
channel ID |
Identifies a live channel by its channel IDThis unique ID identifies a live channel. View this ID by navigating to the Live Channels tab, selecting the desired live channel, and then viewing the GUID option from the Details tab.. |
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. |
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 IDThis unique ID identifies an asset. View this ID by navigating to the Content tab, selecting the desired asset, and then viewing the GUID option from the Details tab. 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.
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 IDThis unique ID identifies an asset. View this ID by navigating to the Content tab, selecting the desired asset, and then viewing the GUID option from the Details tab. 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 IDA user ID uniquely identifies a user account via an alpanumeric system-defined 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. |
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. |
Indicates that a live event was copied.
Field | Description |
---|---|
event ID |
Identifies a live event by its event IDThis unique ID identifies a live event. View this ID by navigating to the Live Events tab, selecting the desired live event, and then viewing the GUID option from the right-hand pane of the Details tab.. |
cause |
Indicates the user IDA user ID uniquely identifies a user account via an alpanumeric system-defined ID. for the user that copied the live event. |
Indicates that a live event was deleted.
Field | Description |
---|---|
event ID |
Identifies a live event by its event IDThis unique ID identifies a live event. View this ID by navigating to the Live Events tab, selecting the desired live event, and then viewing the GUID option from the right-hand pane of the Details tab.. |
cause |
Indicates the user IDA user ID uniquely identifies a user account via an alpanumeric system-defined ID. for the user that deleted the live event. |
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 IDThis unique ID identifies a live event. View this ID by navigating to the Live Events tab, selecting the desired live event, and then viewing the GUID option from the right-hand pane of the Details tab.. |
asset ID |
Indicates the asset IDThis unique ID identifies an asset. View this ID by navigating to the Content tab, selecting the desired asset, and then viewing the GUID option from the Details tab. 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. |
Indicates that a user started watching a live event.
Field | Description |
---|---|
event ID |
Identifies a live event by its event IDThis unique ID identifies a live event. View this ID by navigating to the Live Events tab, selecting the desired live event, and then viewing the GUID option from the right-hand pane of the Details tab.. |
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. |
Indicates that a new playback session was created.
Field | Description |
---|---|
session ID |
Indicates a unique playback session ID. |
content ID |
Indicates a channel IDThis unique ID identifies a live channel. View this ID by navigating to the Live Channels tab, selecting the desired live channel, and then viewing the GUID option from the Details tab., asset IDThis unique ID identifies an asset. View this ID by navigating to the Content tab, selecting the desired asset, and then viewing the GUID option from the Details tab., or event IDThis unique ID identifies a live event. View this ID by navigating to the Live Events tab, selecting the desired live event, and then viewing the GUID option from the right-hand pane of the Details tab. 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 IDA user ID uniquely identifies a user account via an alpanumeric system-defined 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. |
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 IDThis unique ID identifies an asset. View this ID by navigating to the Content tab, selecting the desired asset, and then viewing the GUID option from the Details tab. 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. |
playing owner ID |
Identifies the owner of shared content by user IDA user ID uniquely identifies a user account via an alpanumeric system-defined 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 IDThis unique ID identifies a live channel. View this ID by navigating to the Live Channels tab, selecting the desired live channel, and then viewing the GUID option from the Details tab. when the slice was played in the context of a live channel. Default value: -
|
event ID |
Indicates an event IDThis unique ID identifies a live event. View this ID by navigating to the Live Events tab, selecting the desired live event, and then viewing the GUID option from the right-hand pane of the Details tab. 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 IDAn external ID is a custom ID that you may assign to an asset, live channel, or live event. Typically, this ID reflects a unique value defined in an external database. 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 our technical support.
Indicates that an asset was created due to the start of either a live or VOD slicing job.
Indicates that the slicing job finished.
Field | Description |
---|---|
asset ID |
Indicates the asset IDThis unique ID identifies an asset. View this ID by navigating to the Content tab, selecting the desired asset, and then viewing the GUID option from the Details tab. 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. |
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 |