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:

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 ClosedHow 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 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:

version=001/exec_dt=2024010810/event_type=slice_played/part-00000-3608d733-e96c-4575-8784-41154246e830.c000.csv.gz

In 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=2024010810/event_type=slice_played

Log Data

Key information:

Sample Log File

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

Log Events

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.

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