asyncapi: '2.6.0' id: 'urn:fastly:streaming' info: title: Fastly Streaming, Logging, and Event Surfaces version: '1.0.0' description: | AsyncAPI 2.6 description of the asynchronous and streaming surfaces exposed by Fastly across three documented capabilities: 1. Real-Time Analytics (rt.fastly.com) - long-polling stream of one-second analytics records consumed by following the returned Timestamp field. 2. Real-Time Logging - per-service logging endpoints that push edge log records out to S3, GCS, BigQuery, Splunk, Kafka, Syslog, HTTPS, Datadog, Amazon Kinesis, Google Cloud Pub/Sub, and other documented destinations. 3. Event / Notification surfaces - the Notification Service (which can deliver alerts via outbound webhooks, Slack, Microsoft Teams, PagerDuty, New Relic, and mailing lists), the DDoS Protection Events stream, and the Fanout (Publishing) GRIP-compatible message stream that fans out to HTTP response, HTTP streaming, and WebSocket subscribers. Only surfaces documented at https://www.fastly.com/documentation/reference/api/ are modeled here. Channels are named after the documented destination/transport. contact: name: Fastly Developer Documentation url: https://www.fastly.com/documentation/reference/api/ license: name: Documentation Terms url: https://www.fastly.com/documentation/ defaultContentType: application/json servers: realtime-analytics: url: rt.fastly.com protocol: https description: | Real-Time Analytics base URL. Clients poll a timestamped endpoint and use the Timestamp field of each response as the next request's start_timestamp to receive a continuous one-second-interval stream of analytics records. Responses are cached at the edge with a 1-second TTL. security: - fastlyKey: [] api: url: api.fastly.com protocol: https description: | Primary Fastly control-plane host. Used here as the producer side for Fanout publishes (POST /service/{service_id}/publish/) and as the origin of Notification Service webhook deliveries to customer-configured URLs. security: - fastlyKey: [] - bearerToken: [] customer-webhook: url: '{webhookUrl}' protocol: https description: | Customer-operated HTTPS endpoint that receives outbound notifications from the Fastly Notification Service when an Alert Definition's evaluation strategy crosses its threshold. variables: webhookUrl: description: HTTPS URL configured on the customer's notification integration. default: https://example.com/fastly/notifications customer-https-log: url: '{httpsLogUrl}' protocol: https description: | Customer-operated HTTPS endpoint configured as a Fastly HTTPS logging destination. Fastly POSTs batched log records to this URL after domain ownership validation. variables: httpsLogUrl: description: HTTPS URL of the customer log collector. default: https://logs.example.com/fastly splunk-hec: url: '{splunkUrl}' protocol: https description: Splunk HTTP Event Collector endpoint receiving Fastly edge logs. variables: splunkUrl: default: https://splunk.example.com:8088/services/collector datadog: url: http-intake.logs.datadoghq.com protocol: https description: Datadog HTTP intake receiving Fastly edge logs. aws-s3: url: '{bucket}.s3.amazonaws.com' protocol: https description: Amazon S3 bucket receiving periodic Fastly log batches. variables: bucket: default: my-fastly-logs gcs: url: storage.googleapis.com protocol: https description: Google Cloud Storage bucket receiving periodic Fastly log batches. bigquery: url: bigquery.googleapis.com protocol: https description: Google BigQuery streaming inserts target for Fastly logs. gcp-pubsub: url: pubsub.googleapis.com protocol: https description: Google Cloud Pub/Sub topic receiving Fastly log messages. aws-kinesis: url: kinesis.{region}.amazonaws.com protocol: https description: Amazon Kinesis Data Stream receiving Fastly log messages. variables: region: default: us-east-1 kafka: url: '{broker}' protocol: kafka protocolVersion: '2.x' description: Customer Kafka broker receiving Fastly edge log records. variables: broker: default: kafka.example.com:9092 syslog: url: '{host}' protocol: secure-syslog description: | Syslog-compatible collector (typically TLS on TCP/514 or another port) receiving Fastly streamed log lines. variables: host: default: syslog.example.com:6514 channels: # --------------------------------------------------------------------------- # 1. Real-Time Analytics streaming # --------------------------------------------------------------------------- v1/channel/{service_id}/ts/{start_timestamp}: servers: - realtime-analytics description: | Real-time analytics stream for a service. Each GET returns analytics records (one per second) generated since start_timestamp. The Timestamp field of the response is used as the start_timestamp of the next call, producing a continuous stream of one-second-interval records. parameters: service_id: description: Fastly service identifier. schema: type: string start_timestamp: description: | Unix timestamp; pass the Timestamp returned by the previous response to receive only new records, otherwise pass 0 for the most recent available data. schema: type: integer subscribe: operationId: streamRealtimeStats summary: Stream one-second real-time analytics records for a service. message: $ref: '#/components/messages/RealtimeResponse' v1/channel/{service_id}/ts/h: servers: - realtime-analytics description: | Convenience stream that returns the last 120 seconds of one-second analytics records for a service in a single response. Suitable for bootstrapping a stream before transitioning to the timestamped channel. parameters: service_id: schema: type: string subscribe: operationId: streamRealtimeStatsLast120Seconds message: $ref: '#/components/messages/RealtimeResponse' v1/channel/{service_id}/ts/h/limit/{max_entries}: servers: - realtime-analytics description: | Limited real-time analytics stream returning up to max_entries one-second records from the recent window for a service. parameters: service_id: schema: type: string max_entries: schema: type: integer subscribe: operationId: streamRealtimeStatsLimited message: $ref: '#/components/messages/RealtimeResponse' v1/channel/{service_id}/ts/h/domains/{domain}/limit/{max_entries}: servers: - realtime-analytics description: Domain Inspector real-time metrics stream for a specific domain. parameters: service_id: schema: type: string domain: schema: type: string max_entries: schema: type: integer subscribe: operationId: streamDomainInspectorRealtime message: $ref: '#/components/messages/RealtimeResponse' v1/channel/{service_id}/ts/h/origins/{origin}/limit/{max_entries}: servers: - realtime-analytics description: Origin Inspector real-time metrics stream for a specific origin host. parameters: service_id: schema: type: string origin: schema: type: string max_entries: schema: type: integer subscribe: operationId: streamOriginInspectorRealtime message: $ref: '#/components/messages/RealtimeResponse' # --------------------------------------------------------------------------- # 2. Real-Time Logging endpoints (edge -> destination) # --------------------------------------------------------------------------- logging/s3: servers: - aws-s3 description: | Fastly Real-Time Logging S3 destination. Fastly batches edge log records and uploads them as objects to the configured S3 bucket. publish: operationId: publishLogsToS3 summary: Periodic batched log object uploaded by Fastly to an S3 bucket. message: $ref: '#/components/messages/EdgeLogBatch' logging/gcs: servers: - gcs description: Fastly Real-Time Logging Google Cloud Storage destination. publish: operationId: publishLogsToGCS message: $ref: '#/components/messages/EdgeLogBatch' logging/bigquery: servers: - bigquery description: | Fastly BigQuery logging destination. Log messages are uploaded into the configured BigQuery dataset/table using the configured row format. publish: operationId: publishLogsToBigQuery message: $ref: '#/components/messages/EdgeLogRecord' logging/splunk: servers: - splunk-hec description: | Fastly Splunk logging destination. Fastly POSTs edge log events to the configured Splunk HTTP Event Collector URL. publish: operationId: publishLogsToSplunk message: $ref: '#/components/messages/EdgeLogRecord' logging/kafka: servers: - kafka description: | Fastly Kafka logging destination. Fastly uploads edge log records to the configured topic on the customer's Kafka broker. parameters: {} publish: operationId: publishLogsToKafka message: $ref: '#/components/messages/EdgeLogRecord' bindings: kafka: bindingVersion: '0.4.0' logging/syslog: servers: - syslog description: | Fastly Syslog logging destination. Fastly streams log lines to the configured syslog-compatible host (typically over TLS). publish: operationId: publishLogsToSyslog message: $ref: '#/components/messages/SyslogLogLine' logging/https: servers: - customer-https-log description: | Fastly HTTPS logging destination. After the customer validates domain ownership, Fastly POSTs batched log records to the configured HTTPS URL. publish: operationId: publishLogsToHttps message: $ref: '#/components/messages/EdgeLogBatch' logging/datadog: servers: - datadog description: | Fastly Datadog logging destination. Fastly uploads log messages to the Datadog HTTP intake in the Datadog-specified configuration format. publish: operationId: publishLogsToDatadog message: $ref: '#/components/messages/EdgeLogRecord' logging/kinesis: servers: - aws-kinesis description: | Fastly Amazon Kinesis logging destination. Fastly publishes edge log messages as records on the configured Kinesis Data Stream. publish: operationId: publishLogsToKinesis message: $ref: '#/components/messages/EdgeLogRecord' logging/gcp-pubsub: servers: - gcp-pubsub description: | Fastly Google Cloud Pub/Sub logging destination. Fastly publishes edge log messages to the configured Pub/Sub topic. publish: operationId: publishLogsToPubSub message: $ref: '#/components/messages/EdgeLogRecord' # --------------------------------------------------------------------------- # 3a. Notification Service - outbound webhooks for alerts/incidents # --------------------------------------------------------------------------- notifications/webhook: servers: - customer-webhook description: | Outbound webhook delivered by the Fastly Notification Service when an Alert Definition's evaluation strategy threshold is crossed. The Notification Service supports mailing list, Microsoft Teams, New Relic, Slack, PagerDuty, and webhook integrations; this channel models the webhook transport. publish: operationId: deliverAlertWebhook summary: Alert notification delivered to a customer-configured webhook URL. message: $ref: '#/components/messages/AlertNotification' # --------------------------------------------------------------------------- # 3b. DDoS Protection Events - polled event stream # --------------------------------------------------------------------------- ddos-protection/v1/events: servers: - api description: | DDoS Protection events feed. Clients poll /ddos-protection/v1/events to observe attack events detected by Fastly (active, mitigated, ended) with traffic statistics. Each emitted item is modeled here as an asynchronous DdosEvent record. subscribe: operationId: streamDdosEvents summary: Stream of DDoS Protection events for the account. message: $ref: '#/components/messages/DdosEvent' # --------------------------------------------------------------------------- # 3c. Fanout (Publishing) - GRIP-compatible fan-out to subscribers # --------------------------------------------------------------------------- service/{service_id}/publish/: servers: - api description: | Fastly Publishing (Fanout) ingress. Producers POST a PublishRequest containing PublishItem messages addressed to channels; Fastly Fanout fans each item out to subscribed HTTP responses, HTTP streams, and WebSocket connections using the formats supplied per item. parameters: service_id: description: Fastly service identifier configured for Fanout. schema: type: string publish: operationId: publishFanoutMessage summary: Publish a message into a Fanout channel for real-time delivery. message: $ref: '#/components/messages/PublishRequest' fanout/subscriber/{channel}: servers: - api description: | Logical subscriber-side channel representing the delivery of a Fanout PublishItem to subscribers of {channel}. Delivery transport is selected per item via the formats map (http-response, http-stream, ws-message). parameters: channel: description: Fanout channel name targeted by the publisher. schema: type: string subscribe: operationId: receiveFanoutMessage summary: Receive a Fanout message on a subscribed channel. message: $ref: '#/components/messages/PublishItem' components: securitySchemes: fastlyKey: type: httpApiKey in: header name: Fastly-Key description: Fastly API token passed via the Fastly-Key header. bearerToken: type: http scheme: bearer description: | Fastly API token passed via the Authorization header using the Bearer scheme. Accepted by the Fanout /service/{service_id}/publish/ endpoint. messages: RealtimeResponse: name: RealtimeResponse title: Real-Time Analytics Response summary: One-second-interval analytics records for a Fastly service. contentType: application/json payload: $ref: '#/components/schemas/RealtimeResponse' EdgeLogRecord: name: EdgeLogRecord title: Fastly Edge Log Record summary: | A single log line produced by VCL or Compute log() statements on the Fastly edge and shipped to a logging destination. The body is shaped by the customer's configured format string and may be JSON, plain text, or another structured format depending on the endpoint. contentType: application/json payload: $ref: '#/components/schemas/EdgeLogRecord' EdgeLogBatch: name: EdgeLogBatch title: Fastly Edge Log Batch summary: | Batched object (one upload) containing many EdgeLogRecord entries. Used for object-storage style destinations (S3, GCS, HTTPS POST, etc.) and for the periodic-upload destinations. contentType: application/json payload: $ref: '#/components/schemas/EdgeLogBatch' SyslogLogLine: name: SyslogLogLine title: Fastly Syslog Log Line summary: A single syslog-formatted log line streamed by Fastly. contentType: text/plain payload: type: string description: | Raw syslog line as emitted by the Fastly edge. Content shape is controlled by the customer's logging format. AlertNotification: name: AlertNotification title: Fastly Alert Notification summary: | Notification dispatched when an Alert Definition crosses its threshold. Delivered to the customer-configured webhook URL by the Notification Service. contentType: application/json payload: $ref: '#/components/schemas/AlertNotification' DdosEvent: name: DdosEvent title: Fastly DDoS Protection Event summary: A detected DDoS attack event (active, mitigated, or ended). contentType: application/json payload: $ref: '#/components/schemas/DdosEvent' PublishRequest: name: PublishRequest title: Fastly Fanout PublishRequest summary: Producer-side envelope POSTed to the Fanout publish endpoint. contentType: application/json payload: $ref: '#/components/schemas/PublishRequest' PublishItem: name: PublishItem title: Fastly Fanout PublishItem summary: | A single Fanout message addressed to a channel. The formats map determines which subscriber transports receive the payload. contentType: application/json payload: $ref: '#/components/schemas/PublishItem' schemas: RealtimeResponse: type: object description: | Response from the Real-Time Analytics API. Clients use Timestamp as the start_timestamp of the next request to stream continuous data. properties: Timestamp: type: integer description: Unix timestamp of the latest data point; use as next start_timestamp. AggregateDelay: type: integer description: Offset (seconds) of the latest data point from current time. Data: type: array description: Array of analytics records, each representing one second of data. items: $ref: '#/components/schemas/RealtimeRecord' RealtimeRecord: type: object description: | One second of analytics data, broken down across all POPs and per individual datacenter. properties: recorded: type: integer description: Unix timestamp at which this one-second record was generated. aggregated: type: object description: | Measurements aggregated across all POPs for this second. Contains the full Fastly real-time measurements set (300+ fields covering request counts, cache performance, status codes, bandwidth, bot detection, DDoS actions, Compute, Image Optimizer, WebSocket, etc.). additionalProperties: true datacenter: type: object description: | Measurements grouped by individual POP. Keys are POP codes; values are the same measurements object shape as 'aggregated'. additionalProperties: type: object additionalProperties: true EdgeLogRecord: type: object description: | Generic representation of a single Fastly edge log line. The actual shape is controlled by the format string configured on the logging endpoint, so additional fields are permitted. additionalProperties: true properties: timestamp: type: string format: date-time description: Time at which the record was produced at the edge. service_id: type: string description: Fastly service that produced the log. request_id: type: string description: Request identifier where supplied by VCL/Compute. message: type: string description: Free-form log message body. EdgeLogBatch: type: object description: | A single uploaded object containing one or more EdgeLogRecord entries. Used by object-storage and HTTPS POST destinations. properties: service_id: type: string description: Fastly service that produced the batch. endpoint_name: type: string description: Name of the logging endpoint configuration. records: type: array items: $ref: '#/components/schemas/EdgeLogRecord' AlertNotification: type: object description: | Notification payload describing an alert event derived from a Fastly Alert Definition. Fastly's Notification Service can deliver alerts via webhook, Slack, Microsoft Teams, PagerDuty, New Relic, and mailing list integrations. properties: notification_id: type: string description: Unique identifier for this notification delivery. integration_id: type: string description: Notification integration that produced this delivery. alert_definition: $ref: '#/components/schemas/AlertDefinition' triggered_at: type: string format: date-time description: Time at which the alert condition was observed. state: type: string enum: - triggered - resolved description: Whether the alert was triggered or has resolved. observed_value: type: number description: Value of the monitored metric that crossed the threshold. AlertDefinition: type: object description: | Configuration describing how Fastly observes a metric and the integrations to notify when the threshold is crossed. properties: id: type: string name: type: string service_id: type: string type: type: string enum: - stats - domains - origins metric: type: string evaluation_strategy: type: object description: | Evaluation strategy configuration (operator, threshold, period, ignore_below) describing how the alert is computed. additionalProperties: true integration_ids: type: array items: type: string created_at: type: string format: date-time updated_at: type: string format: date-time DdosEvent: type: object description: A DDoS attack event detected by Fastly DDoS Protection. properties: id: type: string description: Unique event identifier. customer_id: type: string service_id: type: string status: type: string enum: - active - mitigated - ended created_at: type: string format: date-time started_at: type: string format: date-time updated_at: type: string format: date-time ended_at: type: string format: date-time requests_allowed: type: integer description: Count of requests classified as non-attack traffic. requests_detected: type: integer description: Count of requests classified as attack traffic. peak_rps: type: integer description: Peak requests-per-second observed during the event. PublishRequest: type: object description: Envelope POSTed to /service/{service_id}/publish/. properties: items: type: array items: $ref: '#/components/schemas/PublishItem' PublishItem: type: object description: | A single Fanout publish item addressed to a channel. At least one format must be supplied; Fanout delivers only to subscribers whose transport matches a supplied format. properties: channel: type: string example: chat-room-1 description: Channel name the message is published to. id: type: string description: Identifier of this message on the channel. prev_id: type: string description: Previous message identifier on the channel, for ordered delivery. formats: type: object description: Transport-specific payloads keyed by format name. properties: http-response: type: object properties: code: type: integer body: type: string http-stream: type: object properties: content: type: string ws-message: type: object properties: content: type: string