diff --git a/src/docs/sdk/performance/span-operations.mdx b/src/docs/sdk/performance/span-operations.mdx index 98771ad9c6..7f4f211872 100644 --- a/src/docs/sdk/performance/span-operations.mdx +++ b/src/docs/sdk/performance/span-operations.mdx @@ -6,136 +6,259 @@ Span operations are a short code identifying the type of operation the span is m Operations are expected to follow [OpenTelemetry's semantic conventions](https://github.com/open-telemetry/opentelemetry-specification/blob/24de67b3827a4e3ab2515cd8ab62d5bcf837c586/specification/trace/semantic_conventions/README.md) as much as possible. -It's important to keep categories consistent between SDKs and integrations as they are used by Sentry in the [Operations Breakdown](https://docs.sentry.io/product/sentry-basics/tracing/event-detail/#operations-breakdown) feature. For example, both `db.init` and `db.query` will be categorized as database operations (`db`). The default operations breakdown config can be seen [here](https://github.com/getsentry/sentry/blob/809b7fe54c6f06cc1e4c503cf83ded896472a011/src/sentry/projectoptions/defaults.py#L74). +It's important to keep categories consistent between SDKs and integrations as they are used by Sentry in the [Operations Breakdown](https://docs.sentry.io/product/sentry-basics/tracing/event-detail/#operations-breakdown) feature. For example, both `db.init` and `db.query` will be categorized as database operations (`db`). The default operations breakdown config can be seen [here](https://github.com/getsentry/sentry/blob/0fbbf1626f86399b1ca4a2781d66ef96aac69de7/src/sentry/projectoptions/defaults.py#L80). + + + Span operations should use snake_case + # List of Operations The following tables contain examples of operations used by the SDKs and Sentry product. The usage column in the table contains examples of using that operation category, but are not hard recommendations for operation usage. As long as categories stay consistent, SDK developers are free to choose actions and identifiers that best match the use case they are instrumenting. -If a span operation is not provided, the value of `default` is used. +If a span operation is not provided, the value of `default` is set by Relay. + +## General + +| Category | Usage | Description | +| -------- | ----- | --------------------------------------------------- | +| mark | | A general point-in-time span (span with 0 duration) | +| function | | The time it took for a general function to execute | ## Browser -| Category | Usage | Description | -| ---------- | --------------- | ------------------------------------------------------------------------------------------------------------------- | -| pageload | | A full page load of a web application | -| navigation | | Client-side browser history change in a web application | -| resource | | Resource as per [Performance Resource Timing](https://w3c.github.io/resource-timing/#sec-performanceresourcetiming) | -| | resource.script | | -| | resource.link | | -| | resource.css | | -| | resource.img | | -| browser | | Usage of browser APIs or functionality | -| | browser.paint | | -| mark | | Usage of [performance.mark() API](https://developer.mozilla.org/en-US/docs/Web/API/Performance/mark) | -| measure | | Usage of [performance.measure() API](https://developer.mozilla.org/en-US/docs/Web/API/Performance/measure) | -| ui | | | -| | ui.animation | An animation | -| | ui.render | Time it takes to render a UI element | -| | ui.update | Time it takes to update a UI element | +| Category | Usage | Description | +| ---------- | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| pageload | | A full page load of a web application. | +| navigation | | Client-side browser history change in a web application. | +| resource | | Resource as per [Performance Resource Timing](https://w3c.github.io/resource-timing/#sec-performanceresourcetiming). Defaults to `resource.other` if resource cannot be indentified. | +| | resource.script | | +| | resource.link | | +| | resource.css | | +| | resource.img | | +| browser | | Usage of browser APIs or functionality | +| | browser.paint | | +| measure | | Usage of [performance.measure() API](https://developer.mozilla.org/en-US/docs/Web/API/Performance/measure) | +| ui | | | +| | ui.task | A task that is taken on the main UI thread. Typically used to indicate to users about things like the [Long Tasks API](https://developer.mozilla.org/en-US/docs/Web/API/Long_Tasks_API). | +| | ui.render | Time it takes to render a UI element | +| | ui.update | Time it takes to update a UI element | +| | ui.action | A user interaction | +| | ui.action.click | | +| http | | | +| | http.client | | +| | http.graphql.query | | +| | http.graphql.mutation | | +| | http.graphql.subscription | | +| serialize | | Serialization of data | ### JS Frameworks JS Frameworks should be prepended with the `ui` category for operations related to UI components. -| Category | Usage | Description | -| ---------- | --------------- | ----------------------------------------------------------- | -| ui.react | | Spans related to [React](https://reactjs.org/) components | -| | ui.react.mount | | -| | ui.react.render | | -| ui.vue | | Spans related to [Vue.js](https://vuejs.org/) components | -| | ui.vue.mount | | -| | ui.vue.update | | -| ui.angular | | Spans related to [Angular](https://angular.io/) components | -| ui.ember | | Spans related to [EmberJS](https://emberjs.com/) components | +| Category | Usage | Description | +| ---------- | ------------------------------- | ----------------------------------------------------------- | +| ui.react | | Spans related to [React](https://reactjs.org/) components | +| | ui.react.render | | +| | ui.react.update | | +| | ui.react.mount | | +| ui.vue | | Spans related to [Vue.js](https://vuejs.org/) components | +| | ui.vue.activate | | +| | ui.vue.create | | +| | ui.vue.destroy | | +| | ui.vue.mount | | +| | ui.vue.update | | +| ui.svelte | | Spans related to [Svelte](https://svelte.dev/) components | +| | ui.svelte.init | | +| | ui.svelte.update | | +| ui.angular | | Spans related to [Angular](https://angular.io/) components | +| ui.ember | | Spans related to [EmberJS](https://emberjs.com/) components | +| | ui.ember.route.before_model | | +| | ui.ember.route.model | | +| | ui.ember.route.after_model | | +| | ui.ember.route.setup_controller | | ## Web Server Web server related spans should aim to follow OpenTelemetry's [HTTP](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/semantic_conventions/http.md) and [RPC](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/semantic_conventions/rpc.md) semantic conventions when possible. -| Category | Usage | Description | -| --------- | --------------- | ------------------------------------------------------------------ | -| http | | Spans related to http operations | -| | http.client | | -| | http.server | | -| rpc | | Spans related to remote procedure calls (RPC) | -| grpc | | Usage of the [gRPC framework](https://grpc.io/) | -| template | | | -| | template.init | | -| | template.parse | | -| | template.render | | -| render | | Rendering of a view | -| serialize | | Serialization of data | -| console | | Accessing web servers through the command line (ex. Rails console) | - -## Web Frameworks - -| Category | Usage | Description | -| -------- | ----------------- | ----------- | -| django | | | -| | django.middleware | | -| | django.view | | -| express | | | -| rails | | | -| rack | | | +| Category | Usage | Description | +| --------------- | ------------------------------------- | ------------------------------------------------------------------ | +| http | | Spans related to http operations | +| | http.client | | +| | http.server | | +| websocket | | | +| | websocket.server | | +| rpc | | Spans related to remote procedure calls (RPC) | +| grpc | | Usage of the [gRPC framework](https://grpc.io/) | +| graphql | | a GraphQL operation | +| | graphql.execute | | +| | graphql.resolve | | +| | graphql.request | | +| | graphql.query | | +| | graphql.mutation | | +| | graphql.subscription | | +| subprocess | | | +| | subprocess.wait | | +| | subprocess.communicate | | +| middleware | | Usage of webserver middlewares | +| | middleware.express | | +| | middleware.handle | | +| | middleware.starlette | | +| | middleware.django | | +| view | | Rendering of a view | +| | view.process_action.action_controller | | +| | view.render | | +| template | | | +| | template.init | | +| | template.parse | | +| | template.render | | +| | template.django.render | | +| | template.render_template.action_view | | +| function | | | +| function.remix | | Spans related to [Remix](https://remix.run/) data fetchers | +| | function.remix.document_request | | +| | function.remix.action | | +| | function.remix.loader | | +| function.nextjs | | Spans related to [NextJS](https://nextjs.org/) data fetchers | +| serialize | | Serialization of data | +| console | | Accessing web servers through the command line (ex. Rails console) | +| | console.command | | +| file | | Operations on the file system (internal or external) | +| app | | | +| | app.bootstrap | | +| | app.php.autoload | | ## Database Databased related spans are expected to follow OpenTelemetry's [Database](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/semantic_conventions/database.md) semantic conventions when possible. -| Category | Usage | Description | -| -------- | ---------------- | -------------------------- | -| db | | An operation on a database | -| | db.connection | | -| | db.transaction | | -| | db.sql.query | | -| | db.query | | -| | db.query.compile | | -| | db.cache | | +| Category | Usage | Description | +| -------- | -------------------- | -------------------------- | +| db | | An operation on a database | +| | db.query | | +| | db.sql.query | | +| | db.sql.prisma | | +| | db.redis | | +| | db.sql.active_record | | +| | db.sql.execute | | +| cache | | | +| | cache.get_item | | +| | cache.clear | | +| | cache.delete_item | | +| | cache.save | | ## Serverless (FAAS) -Serverless related spans are expected to follow OpenTelemetry's [FaaS](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/semantic_conventions/faas.md) semantic conventions when possible. +Serverless related spans are expected to follow OpenTelemetry's [Function as a Service](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/semantic_conventions/faas.md) (FaaS) semantic conventions when possible. -| Category | Usage | Description | -| -------- | ---------------- | ------------------------------------ | -| faas | | Invocations of a serverless function | -| | faas.aws | | -| | faas.aws.lambda | | -| | faas.aws.request | | -| | faas.gcp | | +| Category | Usage | Description | +| -------------- | ------------------------ | ------------------------------------------- | +| http | | | +| | http.client | | +| | http.client.stream | | +| grpc | | | +| | grpc.client | | +| function.gcp | | Invocations of a GCP function | +| | function.gcp.event | | +| | function.gcp.cloud_event | | +| | function.gcp.http | | +| function.aws | | Invocations of an AWS serverless function | +| | function.aws.lambda | | +| function.azure | | Invocations of an Azure serverless function | ## Mobile -| Category | Usage | Description | -| ---------- | ---------------- | ----------------------------------- | -| app | | Data about the mobile app | -| | app.start | | -| | app.start.warm | | -| | app.start.cold | | -| ui | | An operation on a mobile/desktop UI | -| | ui.load | | -| | ui.action | | -| | ui.action.click | | -| | ui.action.swipe | | -| | ui.action.scroll | | -| navigation | | Navigating to another screen | -| file | | Operations on the file system | -| | file.read | | -| | file.write | | +| Category | Usage | Description | +| ---------- | ------------------------- | ----------------------------- | +| app | | Data about the mobile app | +| | app.start | | +| | app.start.warm | | +| | app.start.cold | | +| ui | | An operation on a mobile UI | +| | ui.load | | +| | ui.action | | +| | ui.action.click | | +| | ui.action.swipe | | +| | ui.action.scroll | | +| navigation | | Navigating to another screen | +| file | | Operations on the file system | +| | file.read | | +| | file.write | | +| serialize | | Serialization of data | +| http | | | +| | http.client | | +| | http.graphql.query | | +| | http.graphql.mutation | | +| | http.graphql.subscription | | + +## Desktop + +| Category | Usage | Description | +| --------- | ------------------------- | ---------------------------- | +| app | | Data about the desktop app | +| | app.start | | +| | app.start.warm | | +| | app.start.cold | | +| ui | | An operation on a desktop UI | +| | ui.load | | +| | ui.action | | +| | ui.action.click | | +| | ui.action.swipe | | +| | ui.action.scroll | | +| serialize | | Serialization of data | +| http | | | +| | http.client | | +| | http.graphql.query | | +| | http.graphql.mutation | | +| | http.graphql.subscription | | ## Messages/Queues Messages/Queue spans are expected follow OpenTelemetry's [Messaging](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/semantic_conventions/messaging.md) semantic conventions when possible. -| Category | Usage | Description | -| -------- | ------------- | ----------- | -| topic | | | -| | topic.send | | -| | topic.recieve | | -| | topic.process | | -| queue | | | -| | queue.process | | -| job | | | -| | job.exec | | -| celery | | | +| Category | Usage | Description | +| -------- | ---------------------- | ----------- | +| topic | | | +| | topic.send | | +| | topic.receive | | +| | topic.process | | +| queue | | | +| | queue.task | | +| | queue.task.celery | | +| | queue.task.rq | | +| | queue.task.delayed_job | | +| | queue.task.active_job | | +| | queue.submit | | +| | queue.submit.celery | | +| | queue.resque | | +| | queue.sidekiq | | + +# Currently Used Categories + +| Category | Description | +| ---------- | ----------- | +| mark | | +| pageload | | +| navigation | | +| resource | | +| browser | | +| measure | | +| ui | | +| app | | +| http | | +| websocket | | +| rpc | | +| grpc | | +| graphql | | +| subprocess | | +| middleware | | +| view | | +| template | | +| serialize | | +| console | | +| db | | +| file | | +| function | | +| topic | | +| queue | |