Skip to content

Commit 815c5c3

Browse files
forstisabellaforstisabella
authored
Merge pull request #7950 from segmentio/granular-observability
Granular Observability Private Beta docs
2 parents c9ebfc7 + 1fb4b31 commit 815c5c3

File tree

4 files changed

+165
-0
lines changed

4 files changed

+165
-0
lines changed

‎src/_data/products.yml‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -196,6 +196,15 @@ items:
196196
slug: custom-domain
197197
plan-note: "Custom Domain is available to customers on Business tier plans."
198198
plans:
199+
free: false
200+
team: false
201+
business: true
202+
add-on: false
203+
204+
- product_display_name: Failure Log Collection
205+
slug: failure-logs
206+
plan-note: "Failure Log Collection is available to customers on Business Tier plans."
207+
plans:
199208
free: false
200209
team: false
201210
business: true

‎src/_data/sidenav/main.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -635,6 +635,8 @@ sections:
635635
title: Default Alerts
636636
- path: /monitor/alerts/custom-alerts
637637
title: Custom Alerts
638+
- path: /monitor/granular-observability
639+
title: Failure Log Collection
638640
- section_title: Protocols
639641
section:
640642
- path: /protocols

‎src/monitor/granular-observability.md‎

Lines changed: 147 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,147 @@
1+
---
2+
title: Failure Log Collection
3+
plan: failure-logs
4+
---
5+
6+
Failure log collection gives you greater visibility into failed event deliveries, allowing you to identify, analyze, and troubleshoot issues with the events that Segment attempted to deliver.
7+
8+
> info "Failure log collection is in private beta"
9+
> During the private beta, failure log collection only supports streaming destinations receiving events from streaming sources or Engage sources.
10+
11+
## Enable failure logs
12+
13+
Before you can access your failure logs using the Public API, you must first enable log collection in the Segment app.
14+
15+
> info ""
16+
> Only users with the [Workspace Owner role](/docs/segment-app/iam/roles/) can enable failure logs.
17+
18+
1. From your Segment workspace, navigate to **Connections > Destinations**.
19+
2. Select one of your destinations and open the Delivery Overview tab.
20+
3. Next to the Date Range picker, select the menu and click **Log collection**.
21+
4. On the Log collection side sheet, turn on the **Collect logs for this destination?** toggle. Take note of the Collection ID, which identifies the logs associated with this destination, as you'll need this to access your failure logs through the Public API.
22+
23+
Once you enable failure logs, Segment starts collecting all events that fail to be delivered to the destination after an attempted delivery and writes them to S3 every hour. The logs are bucketed by the hour in which the original events occurred.
24+
25+
26+
## Access failure logs
27+
28+
Once you've enabled your failure logs in the Segment app, you can access them using Segment's Public API.
29+
30+
Segment has a Public API endpoint, available in [alpha](https://docs.segmentapis.com/tag/Versioning/){:target="_blank”}, that lets you generate presigned S3 URLs for a collection ID and a specific hour in [ISO 8601 format](https://www.iso.org/iso-8601-date-and-time-format.html){:target="_blank”}. Once you've generated a URL, you can only access that data for two hours. If Segment writes additional data to the specified collection and hour time frame, you must generate an additional Public API call to view the updated logs.
31+
32+
You can make up to 120 requests to the failure logs endpoint per day. Some of the request “tokens” replenish every hour. Once Segment collects the observability events, it takes 1-2 hours to populate the log.
33+
34+
The rate limiting metadata follows the Segment API [Rate limit errors](https://docs.segmentapis.com/tag/Rate-Limits/#section/Rate-limit-errors){:target="_blank”} specification and the headers show how many remaining API calls can be made. If you exceed the rate limit, Segment returns a 429 status code.
35+
36+
Here's an example call:
37+
38+
39+
```curl
40+
curl -i -X POST \
41+
'https://api.segmentapis.com/customer-insights/download?collectionId=<COLLECTION ID FROM UI>&hour=<HOUR>' \
42+
-H 'Authorization: Bearer <TOKEN>'
43+
```
44+
45+
> success ""
46+
> Segment retains event logs for 28 days.
47+
48+
## Event types
49+
50+
Logs are formatted as a set of Segment observability events:
51+
- **[Error Logged](#error-logged)**: A Segment event encountered an error. Errors might include retry attempts, discards, or other handling.
52+
- **[Delivery Attempt Logged](#delivery-attempt)**: An attempt was made to deliver an event to a Segment integration.
53+
- **[Destination Exchange Logged](#destination-exchange)**: Captures the integration request and response payloads when delivering one or more Segment events.
54+
55+
### Error logged
56+
57+
Error logged events include basic information about a failed delivery, including the source of an event, which integration it was unable to be delivered to, a reason for the failed delivery, and the time that an error occurred. For more information about common error codes, see Delivery Overview's [Troubleshooting](/docs/connections/delivery-overview/#troubleshooting) documentation.
58+
59+
Here's an example of an Error Logged event:
60+
61+
```json
62+
{
63+
"type": "observability",
64+
"event": "Error Logged",
65+
"version": "v1",
66+
"properties": {
67+
"routed": {
68+
"to": [
69+
{ "type" : "destination", "id" : "abc" }
70+
],
71+
"from": [
72+
{ "type" : "source", "id" : "ghi" }
73+
]
74+
},
75+
"discarded": true | false,
76+
"messageId": "m",
77+
"occurredAt": "2025-03-23T20:00:00Z",
78+
"loggedAt": "2025-03-23T20:00:00Z"
79+
}
80+
}
81+
```
82+
83+
### Delivery attempt
84+
85+
Delivery attempt events contain the request payload and headers Segment sent to a destination, the request payload, status code, and headers sent from a destination, and additional event context, like the current number of delivery attempts, the outcome of the latest delivery attempt, and the last time that Segment attempted a delivery.
86+
87+
Here's an example of a Delivery Attempt Logged event:
88+
89+
```json
90+
{
91+
"type": "observability",
92+
"event": "Delivery Attempt Logged",
93+
"version": "v1",
94+
"properties": {
95+
"routed": {
96+
"to": [
97+
{ "type" : "destination", "id" : "abc" }
98+
],
99+
"from": [
100+
{ "type" : "source", "id" : "ghi" }
101+
]
102+
},
103+
"attempt": 4,
104+
"outcome": "failure",
105+
"destinationExchangeId": "x",
106+
"messageId": "m",
107+
"occurredAt": "2025-03-23T20:00:00Z",
108+
"loggedAt": "2025-03-23T20:00:00Z"
109+
}
110+
}
111+
```
112+
113+
### Destination exchange
114+
Unlike other observability events, destination exchange observability events track **batches** of events delivered to an integration instead of individual events.
115+
116+
Destination exchange events include the source of an event, which integration it was unable to be delivered to, a truncated version of the HTTP request Segment made to an integration, the HTTP response Segment received from an integration, the headers from both the HTTP request and the HTTP responses, and a `destinationExchangeId`, or a UUID that allows you to link the specific exchange to a delivery attempt.
117+
118+
Here's an example of a Delivery Exchange Logged event:
119+
120+
```json
121+
{
122+
"type": "observability",
123+
"event": "Destination Exchange Logged",
124+
"version": "v1",
125+
"properties": {
126+
"requestToDestination": {
127+
"body": "{\"key\": \"value\"}"
128+
},
129+
"responseFromDestination": {
130+
"status" : 418,
131+
"headers": { "X-header": "value" },
132+
"body": "{\"key\": \"value\"}"
133+
},
134+
"routed": {
135+
"to": [
136+
{ "type" : "destination", "id" : "abc" }
137+
],
138+
"from": [
139+
{ "type" : "source", "id" : "ghi" }
140+
]
141+
},
142+
"destinationExchangeId": "x",
143+
"occurredAt": "2025-03-23T20:00:00Z",
144+
"loggedAt": "2025-03-23T20:00:00Z"
145+
}
146+
}
147+
```

‎src/monitor/index.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,3 +16,10 @@ Select a product below to learn about its capabilities, supported destinations,
1616
description="Receive notifications related to the performance and throughput of a Segment connection."
1717
%}
1818

19+
{% include components/reference-button.html
20+
href="/docs/monitor/granular-observability"
21+
icon="book.svg"
22+
title="Failure logs"
23+
description="Get greater visibility into failed event deliveries to better identify, analyze, and troubleshoot issues."
24+
%}
25+

0 commit comments

Comments
 (0)