Skip to content

Commit 7826aa5

Browse files
DebashisBorgohainO2DebashisBorgohainO2
authored
Merge pull request #78 from openobserve/docs-1
added the search traces API doc
2 parents 71256e5 + 696ceae commit 7826aa5

File tree

7 files changed

+187
-13
lines changed

7 files changed

+187
-13
lines changed

‎docs/api/.pages

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,4 +5,4 @@ nav:
55
- Functions: function
66
- Users: user
77
- Cluster: cluster
8-
8+
- Traces: traces

‎docs/api/traces/.pages

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
nav:
2+
3+
- Traces API Overview: index.md
4+
- Search Traces: trace-search-api.md

‎docs/api/traces/index.md

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
2+
This documentation provides comprehensive guidance on using the OpenObserve API to search and retrieve traces from your application. Traces in OpenObserve represent the complete operational flow of requests through your system, showing the full tree of operations and their sub-operations (spans).
3+
4+
??? "What are Traces?"
5+
- **Traces** describe complete operations in your system.
6+
- Each trace represents the full execution path of a request.
7+
- Traces contain multiple **spans** that represent sub-operations or functions.
8+
- Each trace has a unique trace ID.
9+
10+
??? "What are Spans?"
11+
- **Spans** are individual operations within a trace.
12+
- They represent specific functions, service calls, or operations.
13+
- Each span has its own unique span ID.
14+
- Spans are organized in a tree structure within a trace.
15+
16+
??? "Example: OpenObserve Search Operation"
17+
When a user performs a search query in OpenObserve:
18+
19+
- The **trace** represents the entire search operation from query initiation to result return.
20+
- **Spans** might include: alert manager evaluation, query processing, gRPC search execution, cache operations, database interactions.
21+
- You can see the complete flow showing how the operation moves through different OpenObserve services (alert manager → querier → search services).
22+
- Each span shows the duration and status of individual OpenObserve components involved in processing the search request.
23+
24+
## API Endpoints
25+
26+
- [Get latest traces using `/api/{org_id}/{stream_name}/traces/latest`](trace-search-api.md)

‎docs/api/traces/trace-search-api.md

Lines changed: 146 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,146 @@
1+
## Get Latest Traces
2+
3+
Retrieve traces within a specified time range.
4+
5+
**Endpoint** <br>
6+
```
7+
GET /api/{org_id}/{stream_name}/traces/latest
8+
```
9+
10+
**Parameters** <br>
11+
12+
| Parameter | Type | Required | Description |
13+
|-----------|------|----------|-------------|
14+
| `org_id` | string | Yes | Your organization ID |
15+
| `stream_name` | string | Yes | Name of the trace stream |
16+
| `start_time` | integer | Yes | Start time in microseconds |
17+
| `end_time` | integer | Yes | End time in microseconds |
18+
| `from` | integer | Yes | Result start count (pagination offset) |
19+
| `size` | integer | Yes | Number of traces to return |
20+
| `filter` | string | No | Filter query for traces |
21+
22+
**Example Request** <br>
23+
```bash
24+
curl -X GET \
25+
"https://your-openobserve-instance/api/org_id/stream_name/traces/latest?&filter=&start_time=1751443100969000&end_time=1751444000969000&from=0&size=25 \
26+
-H "Authorization: Basic <your-auth-token>"
27+
```
28+
29+
**Response Format**<br>
30+
```json
31+
{
32+
"total": 1,
33+
"trace_id": "b1eeb579ae863bdf9408e7d64c02d5d1",
34+
"hits": [
35+
{
36+
"duration": 9,
37+
"end_time": 1751444644327767600,
38+
"first_event": {
39+
"_timestamp": 1751444644327758,
40+
"duration": 9,
41+
"end_time": 1751444644327767600,
42+
"operation_name": "infra:schema:get_versions",
43+
"service_name": "compactor",
44+
"span_status": "UNSET",
45+
"start_time": 1751444644327758300,
46+
"trace_id": "b1eeb579ae863bdf9408e7d64c02d5d1"
47+
},
48+
"service_name": [
49+
{
50+
"count": 1,
51+
"service_name": "compactor"
52+
}
53+
],
54+
"spans": [1, 0],
55+
"start_time": 1751444644327758300,
56+
"trace_id": "b1eeb579ae863bdf9408e7d64c02d5d1"
57+
}
58+
]
59+
}
60+
```
61+
62+
**Response Fields** <br>
63+
64+
| Field | Description |
65+
|-------|-------------|
66+
| `total` | Total number of traces found |
67+
| `trace_id` | Unique identifier for the trace |
68+
| `hits` | Array of trace objects |
69+
| `duration` | Total duration of the trace in microseconds |
70+
| `start_time` | Trace start time in microseconds |
71+
| `end_time` | Trace end time in microseconds |
72+
| `first_event` | Details of the first span in the trace |
73+
| `service_name` | Array of services involved in the trace |
74+
| `spans` | Array indicating span counts |
75+
76+
## Get Spans Details
77+
78+
Retrieve detailed span information for a specific trace using the traces `/latest` endpoint with a `trace_id` filter.
79+
80+
### Method 1: Using Traces Latest API
81+
82+
**Endpoint**
83+
```
84+
GET /api/{org_id}/{stream_name}/traces/latest?filter=trace_id%{trace_id}&start_time={start_time}&end_time={end_time}&from=0&size=25
85+
```
86+
87+
**Example Request**
88+
```bash
89+
curl -X GET \
90+
"https://your-openobserve-instance/api/your_org/default/traces/latest?filter=trace_id%3Dc2dc93864163b4f0e25342c2b8ca9a8b&start_time=1751443100969000&end_time=1751444000969000&from=0&size=25" \
91+
-H "Authorization: Basic <your-auth-token>"
92+
```
93+
94+
### Method 2: Using Search API
95+
96+
For complex queries, you can use the [search API](https://openobserve.ai/docs/api/search/search/) with SQL queries:
97+
```sql
98+
SELECT * FROM default WHERE trace_id = {trace_id} ORDER BY start_time
99+
```
100+
101+
**Note:** Traces do not support full SQL queries in the traces interface, however, the search API supports SQL for trace data when needed for complex queries.
102+
103+
## Error Handling
104+
105+
Common HTTP Status Codes:
106+
107+
- `200 OK`: Request successful
108+
- `400 Bad Request`: Invalid parameters or query format
109+
- `401 Unauthorized`: Invalid or missing authentication
110+
- `404 Not Found`: Stream or organization not found
111+
- `500 Internal Server Error`: Server error
112+
113+
**Error Response Format** <br>
114+
```json
115+
{
116+
"error": {
117+
"type": "invalid_query",
118+
"message": "Invalid time range specified",
119+
"details": "start_time must be less than end_time"
120+
}
121+
}
122+
```
123+
124+
## Best Practices
125+
126+
**Performance Optimization**:
127+
128+
1. **Use appropriate time ranges**: Avoid overly broad time ranges.
129+
2. **Implement pagination**: Use `from` and `size` parameters for large result sets.
130+
3. **Filter effectively**: Use specific filters to reduce result size.
131+
4. **Cache results**: Cache trace metadata for frequently accessed traces.
132+
133+
**Query Optimization**:
134+
135+
1. **Start with trace metadata**: Use the `/latest` endpoint first to get trace overview.
136+
2. **Fetch spans selectively**: Only fetch detailed spans when needed.
137+
3. **Use specific trace IDs**: When possible, query for specific trace IDs.
138+
139+
**Limitations**:
140+
141+
1. **SQL Query Support**: Full SQL queries are not supported in traces; use filter queries instead.
142+
2. **Time Range Requirement**: Start time and end time are mandatory for all queries.
143+
3. **Result Size Limits**: Large result sets should be paginated using `from` and `size`.
144+
145+
146+

‎docs/user-guide/alerts/destinations.md

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ The **Destinations** section provides three configuration options. Select a dest
1616
**Steps to Configure Webhooks as Alert Destination:**
1717

1818
1. Go to **Management > Alert Destinations**.
19-
2. In the **Add Destinations** page, click **Webhook**.
19+
2. In the **Add Destination** page, click **Webhook**.
2020
3. Fill in the following details:
2121
![Add Destinations](../../images/webook-as-alert-destination.png)
2222
@@ -123,7 +123,7 @@ The **Destinations** section provides three configuration options. Select a dest
123123
![Alert Destination](../../images/alert-email-destination.png)
124124

125125
1. Go to **Management** > **Alert Destinations**.
126-
2. In the **Add Destinations** page, click **Email**.
126+
2. In the **Add Destination** page, click **Email**.
127127
3. Enter a name for the destination.
128128
4. Select an email template to define the alert content.
129129
5. Enter the recipient’s email address.
@@ -149,7 +149,7 @@ The **Destinations** section provides three configuration options. Select a dest
149149
![Action Destination](../../images/action-as-destination.png)
150150

151151
1. Go to **Management > Alert Destinations**.
152-
2. In the **Add Destinations** page, click **Actions**.
152+
2. In the **Add Destination** page, click **Actions**.
153153
3. Enter the name of the destination.
154154
4. Select the template.
155155
5. Select the real-time action.

‎docs/user-guide/identity-and-access-management/.pages

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,6 @@ nav:
22
- Identity and Access Management Overview: index.md
33
- Role-Based Access Control (RBAC): role-based-access-control.md
44
- Enable Role-Based Access Control (RBAC) in Enterprise Edition: enable-rbac-in-openobserve-enterprise.md
5-
- Single Sign-On (SSO): SSO.md
5+
- Single Sign-On (SSO): sso.md
66
- Organizations: organizations.md
77
- Quotas: quotas

‎docs/user-guide/identity-and-access-management/SSO.md

Lines changed: 6 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,9 @@
1+
---
2+
title: Single Sign-On (SSO)
3+
description: Learn how to enable Single Sign-On (SSO) in OpenObserve.
4+
---
5+
<!-- search: SSO, Single Sign-On-->
6+
17
> `Applicable to enterprise version`
28
39
OpenObserve, integrates Single Sign-On (SSO) capabilities using Dex, an OpenID Connect Identity (OIDC) and OAuth 2.0 provider. Dex does not have a user database and instead uses external identity providers like LDAP, Google, GitHub, etc. for authentication.
@@ -251,13 +257,5 @@ connectors:
251257
```
252258

253259

254-
#### OAuth2
255-
256-
TODO
257-
258-
#### Github
259-
260-
TODO
261-
262260

263261

0 commit comments

Comments
 (0)