diff --git a/develop-docs/sdk/data-model/envelope-items.mdx b/develop-docs/sdk/data-model/envelope-items.mdx index e27ee261cf583..fdbe0bfd70b69 100644 --- a/develop-docs/sdk/data-model/envelope-items.mdx +++ b/develop-docs/sdk/data-model/envelope-items.mdx @@ -29,13 +29,13 @@ encoded in JSON. `event_id` : **UUID String, required.** Corresponds to the `event_id` field of the event - payload. Clients are required to generate an event identifier ahead of time - and set it at least in the Envelope headers. If the identifier mismatches - between the Envelope and payload, the Envelope header takes precedence. +payload. Clients are required to generate an event identifier ahead of time +and set it at least in the Envelope headers. If the identifier mismatches +between the Envelope and payload, the Envelope header takes precedence. **Additional Item Headers:** -*None* +_None_ ### Transaction @@ -52,14 +52,14 @@ in JSON. `event_id` : **UUID String, required.** Corresponds to the `event_id` field of the - transaction payload. Clients are required to generate an event identifier - ahead of time and set it at least in the Envelope headers. If the identifier - mismatches between the Envelope and payload, the Envelope header takes - precedence. +transaction payload. Clients are required to generate an event identifier +ahead of time and set it at least in the Envelope headers. If the identifier +mismatches between the Envelope and payload, the Envelope header takes +precedence. **Additional Item Headers:** -*None* +_None_ ### Attachment @@ -91,27 +91,27 @@ file. It is always associated to an event or transaction. `filename` -: **String, required.** The name of the uploaded file without a path component. +: **String, required.** The name of the uploaded file without a path component. `attachment_type` -: *String, optional.* The special type of this attachment. Possible values are: +: _String, optional._ The special type of this attachment. Possible values are: - - **`event.attachment` (default)**: A standard attachment without special - meaning. - - `event.minidump`: A minidump file that creates an error event and is - symbolicated. The file should start with the `MDMP` magic bytes. - - `event.applecrashreport`: An Apple crash report file that creates an error - event and is symbolicated. - - `unreal.context`: An XML file containing UE4 crash meta data. During event - ingestion, event contexts and extra fields are extracted from this file. - - `unreal.logs`: A plain-text log file obtained from UE4 crashes. During - event ingestion, the last logs are extracted into event breadcrumbs. - - `event.view_hierarchy`: An JSON file with a predefined structure, see [RFC #33](https://github.com/getsentry/rfcs/blob/main/text/0033-view-hierarchy.md). +- **`event.attachment` (default)**: A standard attachment without special + meaning. +- `event.minidump`: A minidump file that creates an error event and is + symbolicated. The file should start with the `MDMP` magic bytes. +- `event.applecrashreport`: An Apple crash report file that creates an error + event and is symbolicated. +- `unreal.context`: An XML file containing UE4 crash meta data. During event + ingestion, event contexts and extra fields are extracted from this file. +- `unreal.logs`: A plain-text log file obtained from UE4 crashes. During + event ingestion, the last logs are extracted into event breadcrumbs. +- `event.view_hierarchy`: An JSON file with a predefined structure, see [RFC #33](https://github.com/getsentry/rfcs/blob/main/text/0033-view-hierarchy.md). `content_type` -: *String, optional.* The content type of the attachment payload. Any [MIME type](https://www.iana.org/assignments/media-types/media-types.xhtml) may be used; the default is `application/octet-stream`. +: _String, optional._ The content type of the attachment payload. Any [MIME type](https://www.iana.org/assignments/media-types/media-types.xhtml) may be used; the default is `application/octet-stream`. ### Session @@ -124,11 +124,11 @@ details. **Constraints:** - This Item may occur multiple times per Envelope. -- Ingestion may limit the maximum number of Items per Envelope, see *Ingestion*. +- Ingestion may limit the maximum number of Items per Envelope, see _Ingestion_. **Additional Item Headers:** -*None* +_None_ ### Sessions @@ -140,11 +140,11 @@ details. **Constraints:** - This Item may occur multiple times per Envelope. -- Ingestion may limit the maximum number of Items per Envelope, see *Ingestion*. +- Ingestion may limit the maximum number of Items per Envelope, see _Ingestion_. **Additional Item Headers:** -*None* +_None_ ### Statsd (deprecated) @@ -156,11 +156,11 @@ details. **Constraints:** - This Item may occur multiple times per Envelope. -- Ingestion may limit the maximum number of Items per Envelope, see *Ingestion*. +- Ingestion may limit the maximum number of Items per Envelope, see _Ingestion_. **Additional Item Headers:** -*None* +_None_ ### Metric Meta (deprecated) @@ -173,17 +173,76 @@ details. **Constraints:** - This Item may occur multiple times per Envelope. -- Ingestion may limit the maximum number of Items per Envelope, see *Ingestion*. +- Ingestion may limit the maximum number of Items per Envelope, see _Ingestion_. **Additional Item Headers:** -*None* +_None_ ### User Feedback Item type `"feedback"` contains an event with a feedback context in the payload encoded in JSON. -See the feedback documentation for the payload details. +Example payload: + +```json +{ + "event_id": "9ec79c33ec9942ab8353589fcb2e04dc", + "timestamp": "2011-05-02T17:41:36Z", + "platform": "javascript", + "level": "error", + "contexts": { + "feedback": { + "contact_email": "john@example.com", + "name": "John Smith", + "message": "I love session replay!", + "url": "https://sentry.io/replays/", + "associated_event_id": "32fd1995636d446385016e2747623e11", + "replay_id": "82840977e85b4ed3bc27f7b5b25cec15" + } + } +} +``` + +**Payload Attributes** + +We only document attributes for the `contexts.feedback` object, which is **required** +for this item type. For other attributes, see [Event Payloads](/sdk/data-model/event-payloads/). + +`message` + +: **String, required.** Comments of the user, describing what happened and/or sharing +feedback. The max length is **4096 characters**. + +`contact_email` + +: _String, optional._ The email of the user who submitted the feedback. If excluded, Sentry attempts to fill this in with user context. Anonymous feedbacks (no name or email) are still accepted. + +`name` + +: _String, optional._ The name of the user who submitted the feedback. If excluded, Sentry attempts to fill this in with user context. Anonymous feedbacks (no name or email) are still accepted. + +`url` + +: _String, optional._ The URL of the webpage the user was on when submitting feedback. +This may be used to search for or set alerts on feedback. + +`associated_event_id` + +: _UUID String, optional._ The identifier of an error event in the same project. +Use this to explicitly link a related error in the feedback UI. + +`replay_id` + +: _UUID String, optional._ The identifier of a related Session Replay in the same +project. Sentry uses this ID to render a Replay clip in the feedback UI. + +**Attaching Screenshots:** + +You can associate screenshots with a feedback by sending image data as +[attachment items](/sdk/data-model/envelope-items/#attachment), with `event_id` +corresponding to the feedback item. We recommend sending the items in the same +Envelope. **Constraints:** @@ -195,10 +254,10 @@ See the feedback documentation for t `event_id` : **UUID String, required.** Corresponds to the `event_id` field of the event - payload. **It is not equal to the `associated_event_id`** field in the feedback - context. Clients are required to generate an event identifier ahead of time - and set it at least in the Envelope headers. If the identifier mismatches - between the Envelope and payload, the Envelope header takes precedence. +payload. **It is not equal to the `associated_event_id`** field in the feedback +context. Clients are required to generate an event identifier ahead of time +and set it at least in the Envelope headers. If the identifier mismatches +between the Envelope and payload, the Envelope header takes precedence. ### User Report - Deprecated @@ -207,6 +266,7 @@ Item type `"user_report"`. This is an older, deprecated way of submitting user f This item works by associating user information and comments with an event. If both the item and its associated event are accepted, we convert it to a user feedback. The item contains a JSON payload like this: + ```json {"event_id":"9ec79c33ec9942ab8353589fcb2e04dc","email":"john@example.com","name":"John Me","comments":"It broke."}\n ``` @@ -220,15 +280,15 @@ an error. `email` -: *String, recommended.* The email of the user. +: _String, recommended._ The email of the user. `name` -: *String, recommended.* The name of the user. +: _String, recommended._ The name of the user. `comments` -: *String, recommended.* Comments of the user about what happened. The max length is **4096 characters**. +: _String, recommended._ Comments of the user about what happened. The max length is **4096 characters**. **Constraints:** @@ -245,12 +305,12 @@ an error. `event_id` : **UUID String, required.** Corresponds to the `event_id` field of the payload. - If the identifier mismatches between the Envelope and payload, the Envelope - header takes precedence. +If the identifier mismatches between the Envelope and payload, the Envelope +header takes precedence. **Additional Item Headers:** -*None* +_None_ ### Client Report @@ -266,11 +326,11 @@ details. **Envelope Headers:** -*None* +_None_ **Additional Item Headers:** -*None* +_None_ ### Replay Event @@ -286,15 +346,15 @@ details. **Envelope Headers:** -*None* +_None_ **Additional Item Headers:** -*None* +_None_ ### Replay Recording -Item type `"replay_recording"` contains a replay recording payload encoded in JSON *or* a gzipped JSON. +Item type `"replay_recording"` contains a replay recording payload encoded in JSON _or_ a gzipped JSON. See the replays documentation for the payload details. @@ -306,7 +366,7 @@ details. **Envelope Headers:** -*None* +_None_ **Additional Item Headers:** @@ -326,11 +386,11 @@ in JSON. **Envelope Headers:** -*None* +_None_ **Additional Item Headers:** -*None* +_None_ ### Profile Chunk @@ -339,15 +399,15 @@ in JSON. **Constraints:** -*None* +_None_ **Envelope Headers:** -*None* +_None_ **Additional Item Headers:** -*None* +_None_ ### Check-Ins @@ -363,11 +423,72 @@ details. **Envelope Headers:** -*None* +_None_ + +**Additional Item Headers:** + +_None_ + +### Log + +Item type `"log"` contains an array of log payloads encoded as JSON. This allows for multiple log payloads to be sent in a single envelope item. + +Only a single log item is allowed per envelope. The `item_count` field in the envelope item header must match the amount of logs sent, it's not optional. A `content_type` field in the envelope item header must be set to `application/vnd.sentry.items.log+json`. + +It's okay to mix logs from different traces into the same log envelope item, but if you do, you MUST not attach a DSC (dynamic sampling context) to the envelope header. + +See the Logs documentation for the payload +details. + +Example: + +```json +{ + "type": "log", + "item_count": 5, + "content_type": "application/vnd.sentry.items.log+json" +} +{ + "items": [{..log..}, {..log..}, {..log..}, {..log..}, {..log..}] +} +``` + +**Constraints:** + +_None_ + +**Envelope Headers:** + +_None_ + +**Additional Item Headers:** + +`item_count` + +: **integer, required.** The number of log entries in the envelope. + +`content_type` + +: **string, required.** The content type of the log entries. Must be `application/vnd.sentry.items.log+json`. + +### Otel Logs + +Item type `"otel_log"` contains an OpenTelemetry Logs payload encoded as JSON. Multiple Otel log envelope items can be sent in a single envelope. + +See the Logs documentation for the payload +details. + +**Constraints:** + +_None_ + +**Envelope Headers:** + +_None_ **Additional Item Headers:** -*None* +_None_ ### Reserved Types diff --git a/develop-docs/sdk/telemetry/logs.mdx b/develop-docs/sdk/telemetry/logs.mdx new file mode 100644 index 0000000000000..616e5345f7780 --- /dev/null +++ b/develop-docs/sdk/telemetry/logs.mdx @@ -0,0 +1,417 @@ +--- +title: Logs +sidebar_order: 3 +--- + + + +The Sentry Logs feature is under active development. The information in this document is subject to change. + + + +This document defines the format used by Sentry to ingest logs, as well as the SDK API and behavior that create and send logs to Sentry. + +## Logs Protocol + +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. + +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. + +### `log` Envelope Item Payload + +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. + +```json +{ + "timestamp": 1544719860.0, + "trace_id": "5b8efff798038103d269b633813fc60c", + "level": "info", + "body": "User John has logged in!", + "attributes": { + "sentry.message.template": { + "value": "User %s has logged in!", + "type": "string" + }, + "sentry.message.parameters.0": { + "value": "John", + "type": "string" + }, + "sentry.environment": { + "value": "production", + "type": "string" + }, + "sentry.release": { + "value": "1.0.0", + "type": "string" + }, + "sentry.trace.parent_span_id": { + "value": "b0e6f15b45c36b12", + "type": "string" + } + } +} +``` + +It consists of the following fields: + +`timestamp` + +: **Number, required**. The timestamp of the log in seconds since the Unix epoch. + +`trace_id` + +: **String, required**. The trace id of the log. + +`level` + +: **String, required**. The severity level of the log. One of `trace`, `debug`, `info`, `warn`, `error`, `fatal` (in order of lowest to highest). + +`body` + +: **String, required**. The log body/message. + +`attributes` + +: **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`. In the future arrays will be supported (`string[]`, `boolean[]`, `integer[]`, `double[]`). + +Example: + +```json +{ + "attributes": { + "db.namespace": { + "value": "projects", + "type": "string" + }, + "db.response.returned_rows": { + "value": 123, + "type": "integer" + }, + "db_query_processing_time": { + "value": 123.456, + "type": "double" + }, + "is_production_db": { + "value": false, + "type": "boolean" + } + } +} +``` + +`severity_number` + +: **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. + +### Log Severity Level + +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. + +- `trace` +- `debug` +- `info` +- `warn` +- `error` +- `fatal` + +### Log Severity Number + +The log severity number is an integer that represents the severity of the log. The Sentry's default log severity number maps exactly to [OpenTelemetry's Severity number field](https://opentelemetry.io/docs/specs/otel/logs/data-model/#field-severitynumber) on the OpenTelemetry Logs Spec. + +| SeverityNumber range | Range name | Meaning | +| -------------------- | ---------- | --------------------------------------------------------------------------------------- | +| 1-4 | Trace | A fine-grained debugging event. Typically disabled in default configurations. | +| 5-8 | Debug | A debugging event. | +| 9-12 | Info | An informational event. Indicates that an event happened. | +| 13-16 | Warn | A warning event. Not an error but is likely more important than an informational event. | +| 17-20 | Error | An error event. Something went wrong. | +| 21-24 | Fatal | A fatal error such as application or system crash. | + +Default SDK public API should set the lowest severity number for a given severity level. For example, `warn` severity level logs collected by the SDK API should use the severity number `13`. + +## Public API + +API wise the SDKs are required to expose logging methods which are to be defined in a `logger` module or namespace. The SDKs should also include some initialization options to configure the behavior of logs in the SDK. + +### Initialization Options + +The SDKs must expose the following configuration options: + +- `enableLogs`/`enable_logs`: A boolean flag to control if log envelopes will be generated and sent to Sentry via the Sentry SDK's Logging APIs. If this flag is set to `false`, the SDK should not send logs to Sentry. Defaults to `false`. + +- `beforeSendLog`/`before_send_log`: A function that takes a log object and returns a log object. This function is called before sending the log to Sentry. It can be used to modify the log object or to prevent the log from being sent to Sentry. This function is optional. + +- `logsSampleRate`/`logs_sample_rate`: A number between 0 and 1 that represents the probability that a log will be sent to Sentry. This sampling decision should be made before a log is processed by SDK to lower performance overhead. Defaults to 1.0. + +```js +Sentry.init({ + enableLogs: true, + + beforeSendLog(log) { + // Prevent logs from being sent to Sentry if the plan type is enterprise + if (log.attributes["plan.type"] === "enterprise") { + return null; + } + + return log; + }, + + logsSampleRate: 1.0, +}); +``` + +At the current moment logs sampling decisions are not propagated to downstream services, or be affected by the `tracesSampleRate` configuration option. In the future there might be more advanced client-side sampling and server-side sampling strategies, but this is not yet defined. + +While the logs functionality for an SDK is in an experimental state, SDKs should put these configuration options in an experimental namespace to avoid breaking changes. + +```js +Sentry.init({ + _experiments: { enableLogs: true }, +}); +``` + +### Logger Module + +At minimum the SDK needs to implement the `Sentry.logger.X` (where `X` is the log level) methods. The log levels are `trace`, `debug`, `info`, `warn`, `error`, and `fatal`, which is specced out by the [protocol below](#log-severity-level). + +- `Sentry.logger.trace` +- `Sentry.logger.debug` +- `Sentry.logger.info` +- `Sentry.logger.warn` +- `Sentry.logger.error` +- `Sentry.logger.fatal` + +These methods accepts a string template and the parameters to that string template so the SDK can perform structured logging. Optionally these methods take arbitrary attributes, but not all languages can support both passing a parameterized template and attributes in an easy way. + +```js +// Need to use `fmt` helper function in JavaScript for structured logging. +Sentry.logger.info(Sentry.logger.fmt`Adding item ${itemId} for user ${userId}`); + +Sentry.logger.warn("User %s performed action %s", [userId, actionName], { + extra: "123", +}); +``` + +Aside from accepting attributes, these methods can be overloaded to accept severity number or other parameters if required for the language or platform. + +Beyond the specified methods, SDKs are free to add any extra helpers as they feel is necessary. For example, they could choose to add specialized decorators or helpers for string template creation. + +Below are some example SDK implementations to get you started. These are not finalized versions of the API and individual SDK authors should ensure the logging APIs best fit their platforms. When an SDK implements the logging API, this section should be updated with the SDK's specific implementation. + +#### JavaScript + +```jsx +// Browser JavaScript - need to rely on tagged template literals for string templating +Sentry.logger.info(Sentry.logger.fmt`Adding item ${itemId} for user ${userId}`); + +// Server-side (Node.js, Bun, Deno) with printf-like syntax +Sentry.logger.info("Adding item %s for user %s", [itemId, userId], { + extra: 123, +}); +``` + +#### Python + +```python +# With f-string like syntax +Sentry.logger.info('Adding item {item} for user {user}', item=item_id, user=user_id, attributes={ 'extra': 123 }); +``` + +#### PHP + +```php +use function Sentry\logger; + +logger()->info('Adding item %s for user %s', [$item_id, $user_id], ['extra' => 123]); +``` + +#### Java + +```java +import io.sentry.Sentry; + +// example with MessageFormat based string template +Sentry.logger().info("Adding item {0,string} for user {1,string}", item_id, user_id, log -> { + log.setAttribute("extra", 123); +}); + +// Kotlin +Sentry.Logger.info("Adding item for user") { // fun info(block: LogItem.() -> Unit) + setAttribute("item_id", item_id) + setAttribute("user_id", user_id) + setAttribute("extra", 123) +} +``` + +#### Apple + +```swift +// Swift +SentrySDK.logger + .info(message: "Adding item %s for user %s", + params: [itemId, userId], + attributes: ["extra": @"123"] + ) +``` + +#### Threading and Concurrency Considerations + +Both the `Sentry.logger.X` and `Sentry.logger.emit` methods are fire-and-forget (have no return value). This means that the SDK can choose to run these methods on a separate thread or queue them up for processing later. This includes evaluating the string template, and running any internal hooks (like `beforeSendLog`). The SDK should ensure that the logs are sent in the order they are received. + +It's important to note that putting everything immediately on a background thread has the downside of losing logs that occur directly before a crash. This will come up for Mobile SDKs. Therefore there will need to be a more robust mechanism if a separate thread is used. This mechanism will vary by platform, and the individual SDK will need to figure out the best approach for their platform. + +## SDK Behavior + +### Implementation + +If `debug` is set to `true` in SDK init, calls to the Sentry logger API should also print to the console with the appropriate log level. This will help debugging logging setups. + +Logs should be buffered before being sent. SDKs should keep a buffer of logs on the client (so you can have logs from multiple traces in the buffer) that flushes out based on some kind of condition. A recommended condition is if the buffer length exceeds 25 items, or if 5 seconds have passed. In the future we can use a [weight-tracking based approach](https://github.com/getsentry/rfcs/blob/main/text/0126-sdk-spans-aggregator.md#weight) to determine when to flush logs. + +A new data category for logs has been added to Relay, `log_item`. Both the `log` envelope and `otel_log` envelope is covered by this data category. This will need to implemented in the SDK. Rate limiting applies as usual, there is no special rate limit or rate limiting behaviour for logs. With this data category, client outcomes should be tracked by the SDKs to track how often logs are dropped by the SDK. + +The internal SDK implementation is kept purposefully broad as we are still in early stages. As we figure more out about the logs product and payload characteristics, we'll be able to define a more rigorous spec for logging internals in the SDK. SDKs should take care to not expose logging internals as much as possible to userland so that they can be refactored in the future. + +### Default Attributes + +By default the SDK should set the following attributes: + +1. `sentry.message.template`: The parameterized template string +2. `sentry.message.parameter.X`: The parameters to the template string. X can either be the number that represent the parameter's position in the template string (`sentry.message.parameter.0`, `sentry.message.parameter.1`, etc) or the parameter's name (`sentry.message.parameter.item_id`, `sentry.message.parameter.user_id`, etc) +3. `sentry.environment`: The environment set in the SDK +4. `sentry.release`: The release set in the SDK +5. `sentry.trace.parent_span_id`: The span id of the span that was active when the log was collected. This should not be set if there was no active span. +6. `sentry.sdk.name`: The name of the SDK that sent the log +7. `sentry.sdk.version`: The version of the SDK that sent the log +8. [BACKEND SDKS ONLY] `server.address`: The address of the server that sent the log. Equivalent to `server_name` we attach to errors and transactions. + +Example: + +```json +{ + "sentry.message.template": "Adding item %s for user %s", + "sentry.message.parameter.0": "item_id", + "sentry.message.parameter.1": "user_id", + "sentry.environment": "production", + "sentry.release": "1.0.0", + "sentry.trace.parent_span_id": "b0e6f15b45c36b12", + "sentry.sdk.name": "sentry.javascript.node", + "sentry.sdk.version": "9.11.0", + "server.address": "foo.example.com" +} +``` + +If a log is generated by an SDK integration, the SDK should also set the `sentry.origin` attribute, as per the [Trace Origin](/sdk/telemetry/traces/trace-origin/) documentation. It is assumed that logs without a `sentry.origin` attribute are manually created by the user. + +```json +{ + "sentry.origin": "auto.db.graphql" +} +``` + +Beyond these attributes, we are exploring if the SDK should also send OS, user, and device information automatically (via reading the appropriate contexts from the scope). Given this behaviour can easily be added as a new feature to the SDK, it does not have to be part of the initial SDK implementation until we make a finalized decision. + +### SDK Integrations + +SDKs should aim to have it so that console/logger integrations create logs as per the appropriate log level if `enableLogs`/`enable_logs` is set to true. Examples of this include JavaScript's `console` object and Pythons `logging` standard library. + +If SDK authors feel the need, they can also introduce additional options to beyond `enableLogs`/`enable_logs` to gate this functionality. For example an option to control log appenders added via external config like with `Log4j` in the Java SDK. + +## Appendix A: `otel_log` Envelope Item Payload + + + +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. This is implementation of the [OpenTelemetry Log Data Model](https://opentelemetry.io/docs/specs/otel/logs/data-model/). + +```json +{ + "severity_text": "info", + "body": { + "string_value": "User John has logged in!" + }, + "attributes": [ + { + "key": "sentry.message.template", + "value": { "string_value": "User %s has logged in!" } + }, + { + "key": "sentry.message.parameters.0", + "value": { "string_value": "John" } + } + ], + "time_unix_nano": "1741191250694000000", + "trace_id": "edec519707974fc8bfccb5a017e17394", + "severity_number": 9 +} +``` + +It consists of the following fields: + +`severity_text` + +: **String, required**. The severity level of the log. One of `trace`, `debug`, `info`, `warn`, `error`, `fatal` (in order of lowest to highest). + +`severity_number` + +: **Integer, optional**. The severity number of the log. See [Log Severity Number](#log-severity-number) for more information. + +`trace_id` + +: **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. + +`body` + +: **Object, required**. The log body/message. + +Example: + +```json +{ + "string_value": "Added item to shopping cart" +} +``` + +`attributes` + +: **Array\, 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`. + +Note: `intValue` is a string because JSON only recognizes numbers as floating point values. + +Example: + +```json +{ + "attributes": [ + { + "key": "string_item", + "value": { + "stringValue": "value" + } + }, + { + "key": "integer_item", + "value": { + "intValue": "123" + } + }, + { + "key": "boolean_value", + "value": { + "boolValue": false + } + }, + { + "key": "double_item", + "value": { + "doubleValue": "value" + } + } + ] +} +``` + +`time_unix_nano` + +: **String, optional**. The time the log was created in Unix nanoseconds. If not set, the SDK should set this to the current time. + + diff --git a/develop-docs/sdk/telemetry/traces/trace-origin.mdx b/develop-docs/sdk/telemetry/traces/trace-origin.mdx index 8f3a8d79cf8f2..8896aee4eeafb 100644 --- a/develop-docs/sdk/telemetry/traces/trace-origin.mdx +++ b/develop-docs/sdk/telemetry/traces/trace-origin.mdx @@ -2,11 +2,13 @@ title: Trace Origin --- -Trace origin indicates what created a trace or a span. Not all traces and spans contain enough information +Trace origin indicates what created a trace, span or log. Not all traces, spans or logs contain enough information to tell whether the user or what precisely in the SDK created it. Origin solves this problem. Origin can be sent with -the trace context or spans. -The SDKs should set this value automatically. It is not expected to be set manually by users. The value for origin should rarely change so that we can run proper analytics on them. +the trace context, spans, or logs. + +For logs and standalone spans, the origin should be set as the `sentry.origin` attribute key. +The SDKs should set this value automatically. It is not expected to be set manually by users. The value for origin should rarely change so that we can run proper analytics on them. The origin is of type `string` and consists of four parts: `...`. Only the first is mandatory. The parts build upon each other, meaning it is forbidden @@ -28,12 +30,10 @@ to skip one part. For example, you may send parts one and two but aren't allowed : _Optional_. Is the part of the integration of the SDK that created the trace or span. This is only useful when one integration creates multiple traces or spans, and you'd like to differentiate. Therefore, most of the time, this will be omitted. - All parts can only contain: -* Alphanumeric characters: `a-z` , `A-Z` , and `0-9`. -* Underscores: `_` - +- Alphanumeric characters: `a-z` , `A-Z` , and `0-9`. +- Underscores: `_` ### Examples @@ -53,7 +53,7 @@ All parts can only contain: - `auto.db.core_data` - `auto.db.graphql` -Origins of type `manual` can also have categories and integration names. For example, for the time to display feature, the user manually calls an API of the SDK, +Origins of type `manual` can also have categories and integration names. For example, for the time to display feature, the user manually calls an API of the SDK, creating a span. In this case, the SDK can tell what created the span, but the user did it manually. On the other hand, the SDK also automatically creates a span. In this case we end up with the following origins: @@ -63,5 +63,8 @@ automatically creates a span. In this case we end up with the following origins: ## See also: - Span Interface -- Trace Context +- + Trace Context + +- Logs Interface - Related [RFC](https://github.com/getsentry/rfcs/pull/73/);