Skip to content

Commit 3ff6e56

Browse files
AbhiPrasadAbhiPrasad
committed
Document log envelope item payload
1 parent ff4f76e commit 3ff6e56

File tree

2 files changed

+141
-66
lines changed

2 files changed

+141
-66
lines changed

‎develop-docs/sdk/data-model/envelope-items.mdx

+2-2
Original file line numberDiff line numberDiff line change
@@ -429,7 +429,7 @@ details.
429429

430430
### Logs
431431

432-
Item type `"logs"` contains a logs payload encoded as JSON. Multiple log envelope items can be sent in a single envelope.
432+
Item type `"log"` contains a logs payload encoded as JSON. Multiple log envelope items can be sent in a single envelope.
433433

434434
See the <Link to="/sdk/telemetry/logs">Logs</Link> documentation for the payload
435435
details.
@@ -448,7 +448,7 @@ details.
448448

449449
### Otel Logs
450450

451-
Item type `"otel_logs"` contains an OpenTelemetry Logs payload encoded as JSON. Multiple Otel log envelope items can be sent in a single envelope.
451+
Item type `"otel_log"` contains an OpenTelemetry Logs payload encoded as JSON. Multiple Otel log envelope items can be sent in a single envelope.
452452

453453
See the <Link to="/sdk/telemetry/logs">Logs</Link> documentation for the payload
454454
details.

‎develop-docs/sdk/telemetry/logs.mdx

+139-64
Original file line numberDiff line numberDiff line change
@@ -15,110 +15,90 @@ This document defines the format used by Sentry to ingest logs, as well as the S
1515

1616
There are two ways to send logs to Sentry: via the `log` envelope and Sentry Log protocol (preferred), or the `otel_log` envelope and OpenTelemetry Log protocol.
1717

18-
### `otel_log` Envelope Item Payload
18+
All SDKs are required to send logs via the `log` envelope and Sentry Log protocol. The `otel_log` envelope and OpenTelemetry Log protocol are just documented for completeness and to provide a reference for SDK authors. See the [Appendix A](#appendix-a-otel_log-envelope-item-payload) for the `otel_log` envelope item payload.
1919

20-
The `otel_log` envelope item payload is a JSON object that represents an OpenTelemetry Log. Multiple `otel_log` envelope items can be sent in a single envelope.
20+
### `log` Envelope Item Payload
21+
22+
The `log` envelope item payload is a JSON object that represents a Sentry Log. Multiple `log` envelope items can be sent in a single envelope.
2123

2224
```json
2325
{
24-
"severity_text": "info",
25-
"body": {
26-
"string_value": "User John has logged in!"
27-
},
28-
"attributes": [
29-
{
30-
"key": "sentry.message.template",
31-
"value": { "string_value": "User %s has logged in!" }
26+
"timestamp": 1544719860.0,
27+
"trace_id": "5b8efff798038103d269b633813fc60c",
28+
"level": "info",
29+
"body": "User John has logged in!",
30+
"attributes": {
31+
"sentry.message.template": {
32+
"string_value": "User %s has logged in!"
3233
},
33-
{
34-
"key": "sentry.message.parameters.0",
35-
"value": { "string_value": "John" }
34+
"sentry.message.parameters.0": {
35+
"string_value": "John"
36+
},
37+
"sentry.environment": {
38+
"string_value": "production"
39+
},
40+
"sentry.release": {
41+
"string_value": "1.0.0"
42+
},
43+
"sentry.trace.parent_span_id": {
44+
"string_value": "b0e6f15b45c36b12"
3645
}
37-
],
38-
"time_unix_nano": "1741191250694000000",
39-
"trace_id": "edec519707974fc8bfccb5a017e17394",
40-
"severity_number": 9
46+
}
4147
}
4248
```
4349

4450
It consists of the following fields:
4551

46-
`severity_text`
47-
48-
: **String, required**. The severity level of the log. One of `trace`, `debug`, `info`, `warn`, `error`, `fatal` (in order of lowest to highest).
49-
50-
`severity_number`
52+
`timestamp`
5153

52-
: **Integer, optional**. The severity number of the log. See [Log Severity Number](#log-severity-number) for more information.
54+
: **Number, required**. The timestamp of the log in seconds since the Unix epoch.
5355

5456
`trace_id`
5557

56-
: **Integer, optional**. [HEAVILY RECOMMENDED] The trace id of the log. SDKs should attempt to set this if possible. This is used to link logs to traces and errors in Sentry.
58+
: **String, required**. The trace id of the log.
5759

58-
`body`
60+
`level`
5961

60-
: **Object, required**. The log body/message.
62+
: **String, required**. The severity level of the log. One of `trace`, `debug`, `info`, `warn`, `error`, `fatal` (in order of lowest to highest).
6163

62-
Example:
64+
`body`
6365

64-
```json
65-
{
66-
"string_value": "Added item to shopping cart"
67-
}
68-
```
66+
: **String, required**. The log body/message.
6967

7068
`attributes`
7169

72-
: **Array\<Object\>, optional**. A dictionary of key-value pairs of arbitrary data attached to the log. Attributes must also declare the type of the value. The following types are supported: `string`, `number`, `boolean`, `integer`, `double`.
70+
: **Object, optional**. A dictionary of key-value pairs of arbitrary data attached to the log. Attributes must also declare the type of the value. The following types are supported: `string`, `boolean`, `integer`, `double`.
7371

7472
Note: `intValue` is a string because JSON only recognizes numbers as floating point values.
7573

7674
Example:
7775

7876
```json
7977
{
80-
"attributes": [
81-
{
82-
"key": "string_item",
83-
"value": {
84-
"stringValue": "value"
85-
}
78+
"attributes": {
79+
"string_item": {
80+
"stringValue": "value"
8681
},
87-
{
88-
"key": "integer_item",
89-
"value": {
90-
"intValue": "123"
91-
}
82+
"integer_item": {
83+
"intValue": "123"
9284
},
93-
{
94-
"key": "boolean_value",
95-
"value": {
96-
"boolValue": false
97-
}
85+
"boolean_item": {
86+
"boolValue": true
9887
},
99-
{
100-
"key": "double_item",
101-
"value": {
102-
"doubleValue": "value"
103-
}
88+
"double_item": {
89+
"doubleValue": 123.456
10490
}
105-
]
91+
}
10692
}
10793
```
10894

109-
`time_unix_nano`
110-
111-
: **String, optional**. The time the log was created in Unix nanoseconds. If not set, the SDK should set this to the current time.
112-
113-
### `log` Envelope Item Payload
114-
115-
The `log` envelope item payload is a JSON object that represents a log.
95+
`severity_number`
11696

117-
TODO: Document `log` Envelope Item Payload once finalized.
97+
: **Integer, optional**. The severity number of the log. See [Log Severity Number](#log-severity-number) for more information. This is inferenced from `level` unless explicitly set.
11898

11999
### Log Severity Level
120100

121-
The log severity level is a string that represents the severity of the log. The Sentry's default log severity level maps exactly to [OpenTelemetry's Severity text field](https://opentelemetry.io/docs/specs/otel/logs/data-model/#field-severitytext) on the OpenTelemetry Logs Spec..
101+
The log severity level is a string that represents the severity of the log. The Sentry's default log severity level maps exactly to [OpenTelemetry's Severity text field](https://opentelemetry.io/docs/specs/otel/logs/data-model/#field-severitytext) on the OpenTelemetry Logs Spec.
122102

123103
- `trace`
124104
- `debug`
@@ -379,3 +359,98 @@ Beyond these attributes, we are exploring if the SDK should also send OS, user,
379359
SDKs should aim to have it so that console/logger integrations create logs as per the appropriate log level if `enableSentryLogs` is set to true. Examples of this include JavaScript's `console` methods and Pythons `logging` standard library.
380360

381361
If SDK authors feel the need, they can also introduce additional options to beyond `enableSentryLogs` to gate this functionality. For example an option to control log appenders added via external config like with `Log4j` in the Java SDK.
362+
363+
## Appendix A: `otel_log` Envelope Item Payload
364+
365+
The `otel_log` envelope item payload is a JSON object that represents an OpenTelemetry Log. Multiple `otel_log` envelope items can be sent in a single envelope.
366+
367+
```json
368+
{
369+
"severity_text": "info",
370+
"body": {
371+
"string_value": "User John has logged in!"
372+
},
373+
"attributes": [
374+
{
375+
"key": "sentry.message.template",
376+
"value": { "string_value": "User %s has logged in!" }
377+
},
378+
{
379+
"key": "sentry.message.parameters.0",
380+
"value": { "string_value": "John" }
381+
}
382+
],
383+
"time_unix_nano": "1741191250694000000",
384+
"trace_id": "edec519707974fc8bfccb5a017e17394",
385+
"severity_number": 9
386+
}
387+
```
388+
389+
It consists of the following fields:
390+
391+
`severity_text`
392+
393+
: **String, required**. The severity level of the log. One of `trace`, `debug`, `info`, `warn`, `error`, `fatal` (in order of lowest to highest).
394+
395+
`severity_number`
396+
397+
: **Integer, optional**. The severity number of the log. See [Log Severity Number](#log-severity-number) for more information.
398+
399+
`trace_id`
400+
401+
: **Integer, optional**. [HEAVILY RECOMMENDED] The trace id of the log. SDKs should attempt to set this if possible. This is used to link logs to traces and errors in Sentry.
402+
403+
`body`
404+
405+
: **Object, required**. The log body/message.
406+
407+
Example:
408+
409+
```json
410+
{
411+
"string_value": "Added item to shopping cart"
412+
}
413+
```
414+
415+
`attributes`
416+
417+
: **Array\<Object\>, optional**. A dictionary of key-value pairs of arbitrary data attached to the log. Attributes must also declare the type of the value. The following types are supported: `string`, `number`, `boolean`, `integer`, `double`.
418+
419+
Note: `intValue` is a string because JSON only recognizes numbers as floating point values.
420+
421+
Example:
422+
423+
```json
424+
{
425+
"attributes": [
426+
{
427+
"key": "string_item",
428+
"value": {
429+
"stringValue": "value"
430+
}
431+
},
432+
{
433+
"key": "integer_item",
434+
"value": {
435+
"intValue": "123"
436+
}
437+
},
438+
{
439+
"key": "boolean_value",
440+
"value": {
441+
"boolValue": false
442+
}
443+
},
444+
{
445+
"key": "double_item",
446+
"value": {
447+
"doubleValue": "value"
448+
}
449+
}
450+
]
451+
}
452+
```
453+
454+
`time_unix_nano`
455+
456+
: **String, optional**. The time the log was created in Unix nanoseconds. If not set, the SDK should set this to the current time.

0 commit comments

Comments
 (0)