Log File Delivery

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.

• 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 How do I find this page?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 (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 (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:

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:

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-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. 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

Log Events

Learn about the following log events and their fields:

• ad_beacon_sent
• ad_request_error
• asset_deleted
• asset_play_started
• channel_deleted
• channel_ping
• channel_play_started
• drm_error
• drm_key_read
• error
• event_copied
• event_deleted
• event_ping
• event_play_started
• session_created
• slice_played
• slicing_began
• slicing_ended

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, and Verizon Media Ad Platform Video SSP) 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 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.

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 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: Freewheel: Indicates the smartXML payload sent to FreeWheet during the request. Other Third-Party Ad Servers: Indicates the VAST or VMAP request URL.
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: -

asset_deleted

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.

asset_play_started

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: 0: Normal content 1: Ad
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 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.

channel_deleted

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..

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 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. Learn more about this playback session (session_created).

channel_play_started

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. 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 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.

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 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.

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 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.

event_deleted

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.

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 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. 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 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. 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 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.

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 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: 0: VOD 1: Live channel or live event
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 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.

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 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 new asset.
external ID	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. corresponding to the new asset. Default value: -
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: -
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 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: -

slicing_ended

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: 0: No errors occurred. 1: An error occurred.
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