User Guides

Ad Log File Delivery

The Ad Log File Delivery section focuses on logs related to ad performance. These logs, delivered as compressed CSV files to your Amazon S3 bucket, include detailed information on ad requests, responses, and beacons.

Suggest Edits

Our service may automatically deliver compressed ad log data to an Amazon S3 bucket by submitting HTTPS PUT requests to it. Each request adds an object to the bucket. This object contains a CSV file that uniquely identifies a set of log data and describes one or more log entries. Log fields within a log entry are separated by tabs.

Ad log data is typically delivered within 30 minutes.

Set Up Log Delivery

  1. Create or Identify an Amazon S3 Bucket

  2. Contact Your Account Manager
    Reach out to your account manager to obtain the AWS IAM ARN through which the log data will be delivered.

  3. Authorize the IAM ARN

    • Authorize the identified IAM ARN to perform the following actions on the Amazon S3 bucket:
      • s3:Put*
      • s3:ListBucket
      • s3:GetBucketLocation
    • For details on setting permissions, see the AWS documentation on permissions.

  4. (Optional) Set Up AWS for Log Data Processing

    • Configure AWS services to process the log data posted to the S3 bucket.

    • Example:

      Use AWS Athena to load the CSV files from the bucket and run queries on the log data.

Types of Ad Log Data

Ad log data provides the following information:

  • Jobs: An ad job consists of transactions and beaconing data.

  • Transactions: A transaction consists of requests for ads and the responses provided by an ad decision server. The response may either be a wrapper or a creative.

  • Beaconing Data: Beacons consist of the data reported by our system to the ad decision server.

Job

An ad job consists of transactions and beaconing data.

FieldDescription
Channel Description
String		Identifies the job's channel or live event description.
unique_record_id
String		Identifies this log event via a system-defined ID (UUID).
created_timestamp
String		Indicates the timestamp at which the job was created.
logged_timestamp
String		Indicates the timestamp at which this job was logged.
job_id
Number (Long)		Identifies the ad job via a system-defined ID.
status
String		Indicates whether this job's transactions were completed successfully. Valid values are: complete | fail
ad_request_index
Number (Integer)		Identifies the position of this job's ad break by its index value.
channel_id
String		Identifies the job's live channel by its system-defined ID.
owner_name
String		Identifies the account by name or email address.
asset_type
String		Indicates whether the source video was captured from the Live Slicer or VOD. Valid values are: live | vod
video_id
String		Identifies content by its system-defined ID.
This field does not identify the ad creative corresponding to this job.
viewer_id
String		Identifies the viewer by playback session ID.

Sample Log Data

The following sample log data contains two jobs:

c1ec9765-7ec5-495b-b300-62ebd4b68623  2022-06-08T22:24:17.387Z  2022-06-08T22:24:17.544Z  5e8b711a-d5c6-4b2b-9b33-3c6e90a7a7e3  complete  5 1b3cc490c030410eba27ab3668836e9b  joe@example.com live  7214a224cd5f41c2aa294689dbaatest  0f3d844342d148f2a2fb92a06d38e03a

445168db-0461-46c1-adf8-12f0cc634deb  2022-05-31T01:20:37.979Z  2022-05-31T01:20:39.074Z  f5e5e9e5-a656-4ef5-ab89-24312b1ea3ca  complete  1 ""  joe@example.com  vod 9a497a6ee69test69371499105effbcc  e4818cb063704679b3db0313ca74824a

Request

Request log data describes a request for an ad.

FieldDescription
Wrapper Depth
Number		Indicates the wrapper depth of the request transaction.
unique_record_id
String		Identifies this log event via a system-defined ID (UUID).
created_timestamp
String		Indicates the timestamp at which the request was submitted.
logged_timestamp
String		Indicates the timestamp at which the request was logged.
job_id
Number (Long)		Identifies the ad job via a system-defined ID.
status
String		Indicates whether this job's transactions were completed successfully. Valid values are: complete | fail
request_id
String		Identifies the request by its system-defined ID.
total_elapsed_request_time
Number (Double)		Indicates the total amount of time, in seconds, it took to submit a request and receive a response from the ad decision server.
connection_time
Number (Double)		Indicates the amount of time, in seconds, it took to connect to the ad decision server.
header_request_time
Number (Double)		Indicates the amount of time, in seconds, it took between sending request header data and receiving a response from the ad decision server.
body_download_time
Number (Double)		Indicates the amount of time, in seconds, it took to download the request body.
Example: 3.85284423828125E-4
pod_location
String		Identifies the location of the ad relative to the live stream. Valid values are:
preroll | midroll | postroll
failure_reason
String		Indicates the reason why the job failed. Valid values are: DB_FAILURE | DEADLINE_FAILURE | MISSING_AD_BREAK | MISSING_MEDIA_FILE | NO_FAILURE | PARSER_FAILURE | PROCESSING_TIMEOUT_FAILURE | REQUEST_FAILURE | RESPONSE_FAILURE | UNKNOWN_FAILURE
request_succeeded
Boolean		Indicates whether the request was successful. Valid values are: true | false
A successful request does not indicate that an ad was served to the user. Rather, it indicates that the ad decision server did not return an error.
is_wrapper
Boolean		Indicates whether the request is a wrapper or creative. Valid values are:
  • true: Wrapper
  • false: Creative
start_timestamp
String		Indicates the timestamp at which the request to the ad decision server was submitted.
end_timestamp
String		Indicates the timestamp at which the response from the ad decision server was processed.
parent_request_id
String		Identifies the system-defined ID for the request that is the wrapper for the current request. If the current request does not have a parent, then this field will report None.

Sample Log Data

The following sample log data contains two requests:

64d0985c-f603-43a9-8c1e-ff6af8edf9bb  2022-06-08T18:22:07.055Z  2022-06-08T18:22:07.454Z  a66717b9-a860-4d42-b4cb-41b28f52e5b8  complete  cd500e60-85a2-4a83-80c2-f1323d5403f0  0.3908860683441162  0.013627964080810573  0.377111  1.4710426330566406E-4 ""  ""  true  false 2022-06-08T18:22:07.055Z  2022-06-08T18:22:07.447Z  -

b4df6e49-b99c-487d-9182-dab06d5b1f2b  2022-06-02T18:34:03.676Z  2022-06-02T18:34:03.746Z  d594ee1c-7bb2-44ed-bd36-fdeb9a19cea7  complete  121651e9-ddcc-429f-85b2-06e42f05b5aa  0.05933880805969238 0.0038710416564941424 0.055324  1.437664031982422E-4  ""  ""  true  false 2022-06-02T18:34:03.676Z  2022-06-02T18:34:03.743Z  -

Response

Response log data describes the response from an ad decision server.

FieldDescription
unique_record_id
String		Identifies this log event via a system-defined ID (UUID).
created_timestamp
String		Indicates the timestamp at which the response was submitted.
logged_timestamp
String		Indicates the timestamp at which the response was logged.
job_id
Number (Long)		Identifies the ad job via a system-defined ID.
status
String		Indicates whether this job's transactions were completed successfully. Valid values are: complete | fail
request_id
String		Identifies the request by its system-defined ID.
ad_count
Number (Integer)		Indicates the number of ads served by the ad decision server within this response.
wrapper_count
Number (Integer)		Indicates the number of wrappers contained within this response.
impression_count
Number (Integer)		Indicates the number of impressions that were returned in the response.
range_bytes
Number (Integer)		Indicates the size of the response in bytes.
event_error_message
String		Indicates the error messages that occurred when unwrapping the response. Returns a blank value if an error has not occurred.

Sample Log Data

The following sample log data contains two responses:

8ca26ff8-c819-4746-b441-eca10eba5d58  2022-06-03T22:57:39.775Z  2022-06-03T22:57:40.068Z  db5526f0-5716-47f1-918b-15dea51a3b9d  complete  f29fa7c9-f5fa-4588-bb38-fa833e9ddbe3  1 0 - 27784 ""

2e123bec-167d-4fdc-83f5-198f4cfbe0e7  2022-06-03T23:09:14.081Z  2022-06-03T23:09:14.876Z  59d89267-c140-4a2c-b0d5-51d2e2dcdb1e  complete  4a4dd241-6db4-4b34-9b0f-204a36b62048  7 5 - 223831  ""

Beacon

Beacon data consists of the data exchanged between the ad decision server and our system.

FieldDescription
unique_record_id
String		Identifies this log event via a system-defined ID (UUID).
created_timestamp
String		Indicates the timestamp at which beaconing data was submitted.
logged_timestamp
String		Indicates the timestamp at which beaconing data was logged.
job_id
Number (Long)		Identifies the ad job via a system-defined ID.
beacon_id
String		Identifies the beacon by its system-defined ID.
event_callback_name
String		Identifies the beacon by the name provided by the ad decision server.
url
String		Indicates the beacon's URL.

Sample Log Data

The following sample log data contains two beacons:

b1eaa87c-aad7-460b-a246-7f43dee1d1ac  2022-06-07T17:40:06.332Z  2022-06-07T17:40:06.332Z  e298612f-fa3f-4c46-98b5-7d78a8be4ee4  e298612f-fa3f-4c46-98b5-7d78a8be4ee4-0-1--thirdquartiles-0  thirdquartiles  https://example.com/proxy/tracker/v2?pid=5dee561f0221d82b5b694bad8d6ceed4fe1514fc9f6378988d4725efb2c7598f&tid=e27841dc-208f-4ae2-8626-e9d9cf8e2028&dcid=9d63ca75-70d2-49ca-931e-03a2b4504279&cf=short_form&loc=CMgGECwYTSDvBC2PwgNCNRSuwcI6BmRhbGxhc0IFNzUyNDQ&rnd=%5BCACHEBUSTING%5D&acp.rqt=linear&tz=-04%3A00&rbp=3&aid=7ffed83c-44ad-3ce9-be7c-ce0f63b276da&tt=m&icd_tnr=1&icd_lkpt=2022-06-07T14%3A40%3A31Z&icd_bid=0&icd_bct=1654623510&icd_vm=1&icd_ibid=c907150b-de95-464a-88d8-f1a09fbd40ed&icd_cs=DISCHD_305&icd_ai=YVCX17792FN&icd_nz=305&icd_srid=550&edge_adtype=0&icd_adr=350082&icd_olt=5&ad_dur=30&e=17

9cb4688f-911e-4df4-99e8-95bccf575fad  2022-06-01T03:03:24.886Z  2022-06-01T03:03:24.886Z  ae816075-9654-4af2-be85-87aad4c94528  ae816075-9654-4af2-be85-87aad4c94528-0-0--impressions-0 impressions https://example.com/live/pcs/view?xai=AKAOjsuwtiF_KOwoxeL6uLmnAqnLePfFV0Eh95Q7PXbvk1hMekiBt6VXJNMiCeiL2ou0gMAo4gXBzY56QdcLYtaoGYlUdioG4dlFx7PyBLx84iT2CY-tEVMLbzvCYXywSnh4ElOSGx5H33lMNLqRg2cOOUGnchOZkGvj_5QQwdikj7kciJ1hrU7reJ0hQo0UKMaRPsVSQwAiQ3BWtmtPuiqMThqLf2nm_voBDKIRVoillY3SppcZDJoj79n7pNxF18sMBFzf5bsZjU4EWbNo2oYabRJTY4sU9d90Ol3K-gofi55vC1YlnJ_ukQXZD9s&sai=AMfl-YTQQnBeH5AC3eyZVGSfYwNXc7Io7mxEjzn_W59ZvrVj&sig=Cg0ArKJSzOt2_tBqik2iEAE&uach_m=[UACH]&adurl=

Timestamps

Timestamps are reported using the following syntax:

YYYY-MM-DDThh:mm:ss.sZ

The variables used for the date and the date/time formats are described below.

VariableDescription
YYYYRepresents a year in the Gregorian calendar using a four digit number (e.g., 2023).
MMRepresents a two digit month between 01 (January) and 12 (December).
DDRepresents a two digit day between 01 and 31.
TIndicates a delimiter between date and time. This delimiter is only required if you would like to specify a time. Keep in mind that time must be specified using 24-hour clock notation in UTC/GMT.
hhRepresents a two digit hour between 00 (midnight) and 23 (11 p.m.).
mmRepresents the number of minutes (i.e., 00 - 59) into the specified hour.
ssRepresents the number of seconds (i.e., 00 - 59) into the specified minute.
sRepresents the millionths (i.e., 000000 - 999999) into the specified second.
ZRepresents UTC time.

Example

2019-06-29T03:13:07.340889Z

Updated 25 days ago