diff --git a/config/_default/menus/api.en.yaml b/config/_default/menus/api.en.yaml index e850f44d14c..264da69c9f9 100644 --- a/config/_default/menus/api.en.yaml +++ b/config/_default/menus/api.en.yaml @@ -9966,6 +9966,22 @@ menu: - ListProcesses unstable: [] order: 1 + - name: Product Analytics + url: /api/latest/product-analytics/ + identifier: product-analytics + generated: true + - name: Send server-side events + url: '#send-server-side-events' + identifier: product-analytics-send-server-side-events + parent: product-analytics + generated: true + params: + versions: + - v2 + operationids: + - SubmitProductAnalyticsEvent + unstable: [] + order: 1 - name: RUM url: /api/latest/rum/ identifier: rum diff --git a/content/en/api/latest/product-analytics/_index.md b/content/en/api/latest/product-analytics/_index.md new file mode 100644 index 00000000000..6fd972ee1e3 --- /dev/null +++ b/content/en/api/latest/product-analytics/_index.md @@ -0,0 +1,3 @@ +--- +title: Product Analytics +--- diff --git a/content/en/api/v2/product-analytics/_index.md b/content/en/api/v2/product-analytics/_index.md new file mode 100644 index 00000000000..2474faa86e5 --- /dev/null +++ b/content/en/api/v2/product-analytics/_index.md @@ -0,0 +1,4 @@ +--- +title: Product Analytics +headless: true +--- diff --git a/content/en/api/v2/product-analytics/examples.json b/content/en/api/v2/product-analytics/examples.json new file mode 100644 index 00000000000..01ea5b8f274 --- /dev/null +++ b/content/en/api/v2/product-analytics/examples.json @@ -0,0 +1,145 @@ +{ + "SubmitProductAnalyticsEvent": { + "responses": { + "202": { + "json": {}, + "html": "
\n
\n
\n

No response body

\n
\n
\n
" + }, + "400": { + "json": { + "errors": [ + { + "detail": "Malformed payload", + "status": "400", + "title": "Bad Request" + } + ] + }, + "html": "
\n
\n
\n
\n

errors

\n
\n

[object]

\n

Structured errors.

\n
\n
\n
\n
\n
\n

detail

\n
\n

string

\n

Error message.

\n
\n \n
\n
\n
\n
\n
\n

status

\n
\n

string

\n

Error code.

\n
\n \n
\n
\n
\n
\n
\n

title

\n
\n

string

\n

Error title.

\n
\n \n
\n
\n
\n
" + }, + "401": { + "json": { + "errors": [ + { + "detail": "Malformed payload", + "status": "400", + "title": "Bad Request" + } + ] + }, + "html": "
\n
\n
\n
\n

errors

\n
\n

[object]

\n

Structured errors.

\n
\n
\n
\n
\n
\n

detail

\n
\n

string

\n

Error message.

\n
\n \n
\n
\n
\n
\n
\n

status

\n
\n

string

\n

Error code.

\n
\n \n
\n
\n
\n
\n
\n

title

\n
\n

string

\n

Error title.

\n
\n \n
\n
\n
\n
" + }, + "403": { + "json": { + "errors": [ + { + "detail": "Malformed payload", + "status": "400", + "title": "Bad Request" + } + ] + }, + "html": "
\n
\n
\n
\n

errors

\n
\n

[object]

\n

Structured errors.

\n
\n
\n
\n
\n
\n

detail

\n
\n

string

\n

Error message.

\n
\n \n
\n
\n
\n
\n
\n

status

\n
\n

string

\n

Error code.

\n
\n \n
\n
\n
\n
\n
\n

title

\n
\n

string

\n

Error title.

\n
\n \n
\n
\n
\n
" + }, + "408": { + "json": { + "errors": [ + { + "detail": "Malformed payload", + "status": "400", + "title": "Bad Request" + } + ] + }, + "html": "
\n
\n
\n
\n

errors

\n
\n

[object]

\n

Structured errors.

\n
\n
\n
\n
\n
\n

detail

\n
\n

string

\n

Error message.

\n
\n \n
\n
\n
\n
\n
\n

status

\n
\n

string

\n

Error code.

\n
\n \n
\n
\n
\n
\n
\n

title

\n
\n

string

\n

Error title.

\n
\n \n
\n
\n
\n
" + }, + "413": { + "json": { + "errors": [ + { + "detail": "Malformed payload", + "status": "400", + "title": "Bad Request" + } + ] + }, + "html": "
\n
\n
\n
\n

errors

\n
\n

[object]

\n

Structured errors.

\n
\n
\n
\n
\n
\n

detail

\n
\n

string

\n

Error message.

\n
\n \n
\n
\n
\n
\n
\n

status

\n
\n

string

\n

Error code.

\n
\n \n
\n
\n
\n
\n
\n

title

\n
\n

string

\n

Error title.

\n
\n \n
\n
\n
\n
" + }, + "429": { + "json": { + "errors": [ + { + "detail": "Malformed payload", + "status": "400", + "title": "Bad Request" + } + ] + }, + "html": "
\n
\n
\n
\n

errors

\n
\n

[object]

\n

Structured errors.

\n
\n
\n
\n
\n
\n

detail

\n
\n

string

\n

Error message.

\n
\n \n
\n
\n
\n
\n
\n

status

\n
\n

string

\n

Error code.

\n
\n \n
\n
\n
\n
\n
\n

title

\n
\n

string

\n

Error title.

\n
\n \n
\n
\n
\n
" + }, + "500": { + "json": { + "errors": [ + { + "detail": "Malformed payload", + "status": "400", + "title": "Bad Request" + } + ] + }, + "html": "
\n
\n
\n
\n

errors

\n
\n

[object]

\n

Structured errors.

\n
\n
\n
\n
\n
\n

detail

\n
\n

string

\n

Error message.

\n
\n \n
\n
\n
\n
\n
\n

status

\n
\n

string

\n

Error code.

\n
\n \n
\n
\n
\n
\n
\n

title

\n
\n

string

\n

Error title.

\n
\n \n
\n
\n
\n
" + }, + "503": { + "json": { + "errors": [ + { + "detail": "Malformed payload", + "status": "400", + "title": "Bad Request" + } + ] + }, + "html": "
\n
\n
\n
\n

errors

\n
\n

[object]

\n

Structured errors.

\n
\n
\n
\n
\n
\n

detail

\n
\n

string

\n

Error message.

\n
\n \n
\n
\n
\n
\n
\n

status

\n
\n

string

\n

Error code.

\n
\n \n
\n
\n
\n
\n
\n

title

\n
\n

string

\n

Error title.

\n
\n \n
\n
\n
\n
" + } + }, + "request": { + "json_curl": { + "account": { + "id": "account-67890" + }, + "application": { + "id": "123abcde-123a-123b-1234-123456789abc" + }, + "event": { + "name": "payment.processed" + }, + "session": { + "id": "session-abcdef" + }, + "type": "server", + "usr": { + "id": "user-12345" + } + }, + "json": { + "account": { + "id": "account-67890" + }, + "application": { + "id": "123abcde-123a-123b-1234-123456789abc" + }, + "event": { + "name": "payment.processed" + }, + "session": { + "id": "session-abcdef" + }, + "type": "server", + "usr": { + "id": "user-12345" + } + }, + "html": "
\n
\n
\n
\n

account

\n
\n

object

\n

The account linked to your event.

\n
\n
\n
\n
\n
\n

id [required]

\n
\n

string

\n

The account ID used in Datadog.

\n
\n \n
\n
\n
\n
\n
\n
\n
\n

application [required]

\n
\n

object

\n

The application in which you want to send your events.

\n
\n
\n
\n
\n
\n

id [required]

\n
\n

string

\n

The application ID of your application. It can be found in your\napplication management page.

\n
\n \n
\n
\n
\n
\n
\n
\n
\n

event [required]

\n
\n

object

\n

Fields used for the event.

\n
\n
\n
\n
\n
\n

name [required]

\n
\n

string

\n

The name of your event, which is used for search in the same way as view or action names.

\n
\n \n
\n
\n
\n
\n
\n
\n
\n

session

\n
\n

object

\n

The session linked to your event.

\n
\n
\n
\n
\n
\n

id [required]

\n
\n

string

\n

The session ID captured by the SDK.

\n
\n \n
\n
\n
\n
\n
\n
\n
\n

type [required]

\n
\n

enum

\n

The type of Product Analytics event. Must be server for server-side events. \nAllowed enum values: server

\n
\n \n
\n
\n
\n
\n
\n

usr

\n
\n

object

\n

The user linked to your event.

\n
\n
\n
\n
\n
\n

id [required]

\n
\n

string

\n

The user ID used in Datadog.

\n
\n \n
\n
\n
\n
" + } + } +} \ No newline at end of file diff --git a/data/api/v2/full_spec.yaml b/data/api/v2/full_spec.yaml index 6a213329b66..d62b941ca20 100644 --- a/data/api/v2/full_spec.yaml +++ b/data/api/v2/full_spec.yaml @@ -41471,6 +41471,114 @@ components: type: string x-enum-varnames: - PROCESS + ProductAnalyticsServerSideEventError: + description: Error details. + properties: + detail: + description: Error message. + example: Malformed payload + type: string + status: + description: Error code. + example: '400' + type: string + title: + description: Error title. + example: Bad Request + type: string + type: object + ProductAnalyticsServerSideEventErrors: + description: Error response. + properties: + errors: + description: Structured errors. + items: + $ref: '#/components/schemas/ProductAnalyticsServerSideEventError' + type: array + type: object + ProductAnalyticsServerSideEventItem: + description: A Product Analytics server-side event. + properties: + account: + $ref: '#/components/schemas/ProductAnalyticsServerSideEventItemAccount' + application: + $ref: '#/components/schemas/ProductAnalyticsServerSideEventItemApplication' + event: + $ref: '#/components/schemas/ProductAnalyticsServerSideEventItemEvent' + session: + $ref: '#/components/schemas/ProductAnalyticsServerSideEventItemSession' + type: + $ref: '#/components/schemas/ProductAnalyticsServerSideEventItemType' + usr: + $ref: '#/components/schemas/ProductAnalyticsServerSideEventItemUsr' + required: + - application + - event + - type + type: object + ProductAnalyticsServerSideEventItemAccount: + description: The account linked to your event. + properties: + id: + description: The account ID used in Datadog. + example: account-67890 + type: string + required: + - id + type: object + ProductAnalyticsServerSideEventItemApplication: + description: The application in which you want to send your events. + properties: + id: + description: 'The application ID of your application. It can be found in + your + + [application management page](https://app.datadoghq.com/rum/list).' + example: 123abcde-123a-123b-1234-123456789abc + type: string + required: + - id + type: object + ProductAnalyticsServerSideEventItemEvent: + description: Fields used for the event. + properties: + name: + description: The name of your event, which is used for search in the same + way as view or action names. + example: payment.processed + type: string + required: + - name + type: object + ProductAnalyticsServerSideEventItemSession: + description: The session linked to your event. + properties: + id: + description: The session ID captured by the SDK. + example: session-abcdef + type: string + required: + - id + type: object + ProductAnalyticsServerSideEventItemType: + description: The type of Product Analytics event. Must be `server` for server-side + events. + enum: + - server + example: server + type: string + x-enum-varnames: + - SERVER + ProductAnalyticsServerSideEventItemUsr: + description: The user linked to your event. + properties: + id: + description: The user ID used in Datadog. + example: user-12345 + type: string + required: + - id + type: object Project: description: A Project properties: @@ -78514,6 +78622,219 @@ paths: x-permission: operator: OPEN permissions: [] + /api/v2/prodlytics: + post: + description: 'Send server-side events to Product Analytics. Server-side events + are retained for 15 months. + + + Server-Side events in Product Analytics are helpful for tracking events that + occur on the server, + + as opposed to client-side events, which are captured by Real User Monitoring + (RUM) SDKs. + + This allows for a more comprehensive view of the user journey by including + actions that happen on the server. + + Typical examples could be `checkout.completed` or `payment.processed`. + + + Ingested server-side events are integrated into Product Analytics to allow + users to select and filter + + these events in the event picker, similar to how views or actions are handled. + + + **Requirements:** + + - At least one of `usr`, `account`, or `session` must be provided with a valid + ID. + + - The `application.id` must reference a Product Analytics-enabled application. + + + **Custom Attributes:** + + Any additional fields in the payload are flattened and searchable as facets. + + For example, a payload with `{"customer": {"tier": "premium"}}` is searchable + with + + the syntax `@customer.tier:premium` in Datadog. + + + The status codes answered by the HTTP API are: + + - 202: Accepted: The request has been accepted for processing + + - 400: Bad request (likely an issue in the payload formatting) + + - 401: Unauthorized (likely a missing API Key) + + - 403: Permission issue (likely using an invalid API Key) + + - 408: Request Timeout, request should be retried after some time + + - 413: Payload too large (batch is above 5MB uncompressed) + + - 429: Too Many Requests, request should be retried after some time + + - 500: Internal Server Error, the server encountered an unexpected condition + that prevented it from fulfilling the request, request should be retried after + some time + + - 503: Service Unavailable, the server is not ready to handle the request + probably because it is overloaded, request should be retried after some time' + operationId: SubmitProductAnalyticsEvent + requestBody: + content: + application/json: + examples: + event-with-account: + description: Send a server-side event linked to an account. + summary: Event with account ID + value: + account: + id: account-456 + application: + id: 123abcde-123a-123b-1234-123456789abc + event: + name: checkout.completed + type: server + event-with-custom-attributes: + description: Send a server-side event with additional custom attributes. + summary: Event with custom attributes + value: + application: + id: 123abcde-123a-123b-1234-123456789abc + customer: + tier: premium + event: + name: payment.processed + type: server + usr: + id: '123' + event-with-session: + description: Send a server-side event linked to a session. + summary: Event with session ID + value: + application: + id: 123abcde-123a-123b-1234-123456789abc + event: + name: form.submitted + session: + id: session-789 + type: server + simple-event-with-user: + description: Send a server-side event linked to a user. + summary: Simple event with user ID + value: + application: + id: 123abcde-123a-123b-1234-123456789abc + event: + name: payment.processed + type: server + usr: + id: '123' + schema: + $ref: '#/components/schemas/ProductAnalyticsServerSideEventItem' + description: Server-side event to send (JSON format). + required: true + responses: + '202': + content: + application/json: + schema: + type: object + description: Request accepted for processing (always 202 empty JSON). + '400': + content: + application/json: + schema: + $ref: '#/components/schemas/ProductAnalyticsServerSideEventErrors' + description: Bad Request + '401': + content: + application/json: + schema: + $ref: '#/components/schemas/ProductAnalyticsServerSideEventErrors' + description: Unauthorized + '403': + content: + application/json: + schema: + $ref: '#/components/schemas/ProductAnalyticsServerSideEventErrors' + description: Forbidden + '408': + content: + application/json: + schema: + $ref: '#/components/schemas/ProductAnalyticsServerSideEventErrors' + description: Request Timeout + '413': + content: + application/json: + schema: + $ref: '#/components/schemas/ProductAnalyticsServerSideEventErrors' + description: Payload Too Large + '429': + content: + application/json: + schema: + $ref: '#/components/schemas/ProductAnalyticsServerSideEventErrors' + description: Too Many Requests + '500': + content: + application/json: + schema: + $ref: '#/components/schemas/ProductAnalyticsServerSideEventErrors' + description: Internal Server Error + '503': + content: + application/json: + schema: + $ref: '#/components/schemas/ProductAnalyticsServerSideEventErrors' + description: Service Unavailable + security: + - apiKeyAuth: [] + servers: + - url: https://{subdomain}.{site} + variables: + site: + default: datadoghq.com + description: The regional site for customers. + enum: + - datadoghq.com + - us3.datadoghq.com + - us5.datadoghq.com + - ap1.datadoghq.com + - ap2.datadoghq.com + - datadoghq.eu + subdomain: + default: browser-intake + description: The subdomain where the API is deployed. + - url: '{protocol}://{name}' + variables: + name: + default: browser-intake-datadoghq.com + description: Full site DNS name. + protocol: + default: https + description: The protocol for accessing the API. + - url: https://{subdomain}.{site} + variables: + site: + default: datadoghq.com + description: Any Datadog deployment. + subdomain: + default: browser-intake + description: The subdomain where the API is deployed. + summary: Send server-side events + tags: + - Product Analytics + x-codegen-request-body-name: body + x-menu-order: 1 /api/v2/product-analytics/accounts/facet_info: post: description: Get facet information for account attributes including possible @@ -91545,6 +91866,18 @@ tags: See the [Live Processes page](https://docs.datadoghq.com/infrastructure/process/) for more information. name: Processes +- description: 'Send server-side events to Product Analytics. Server-Side Events Ingestion + allows you to collect custom events + + from any server-side source, and retains events for 15 months. Server-side events + are helpful for understanding + + causes of a funnel drop-off which are external to the client-side (for example, + payment processing error). + + See the [Product Analytics page](https://docs.datadoghq.com/product_analytics/) + for more information.' + name: Product Analytics - description: Manage your Real User Monitoring (RUM) applications, and search or aggregate your RUM events over HTTP. See the [RUM & Session Replay page](https://docs.datadoghq.com/real_user_monitoring/) for more information diff --git a/data/api/v2/translate_actions.json b/data/api/v2/translate_actions.json index 222fc7b9c11..227ba1bf27b 100644 --- a/data/api/v2/translate_actions.json +++ b/data/api/v2/translate_actions.json @@ -2141,6 +2141,12 @@ "description": "Get all processes for your organization.", "summary": "Get all processes" }, + "SubmitProductAnalyticsEvent": { + "description": "Send server-side events to Product Analytics. Server-side events are retained for 15 months.\n\nServer-Side events in Product Analytics are helpful for tracking events that occur on the server,\nas opposed to client-side events, which are captured by Real User Monitoring (RUM) SDKs.\nThis allows for a more comprehensive view of the user journey by including actions that happen on the server.\nTypical examples could be `checkout.completed` or `payment.processed`.\n\nIngested server-side events are integrated into Product Analytics to allow users to select and filter\nthese events in the event picker, similar to how views or actions are handled.\n\n**Requirements:**\n- At least one of `usr`, `account`, or `session` must be provided with a valid ID.\n- The `application.id` must reference a Product Analytics-enabled application.\n\n**Custom Attributes:**\nAny additional fields in the payload are flattened and searchable as facets.\nFor example, a payload with `{\"customer\": {\"tier\": \"premium\"}}` is searchable with\nthe syntax `@customer.tier:premium` in Datadog.\n\nThe status codes answered by the HTTP API are:\n- 202: Accepted: The request has been accepted for processing\n- 400: Bad request (likely an issue in the payload formatting)\n- 401: Unauthorized (likely a missing API Key)\n- 403: Permission issue (likely using an invalid API Key)\n- 408: Request Timeout, request should be retried after some time\n- 413: Payload too large (batch is above 5MB uncompressed)\n- 429: Too Many Requests, request should be retried after some time\n- 500: Internal Server Error, the server encountered an unexpected condition that prevented it from fulfilling the request, request should be retried after some time\n- 503: Service Unavailable, the server is not ready to handle the request probably because it is overloaded, request should be retried after some time", + "summary": "Send server-side events", + "request_description": "Server-side event to send (JSON format).", + "request_schema_description": "A Product Analytics server-side event." + }, "GetAccountFacetInfo": { "description": "Get facet information for account attributes including possible values and counts", "summary": "Get account facet info", diff --git a/data/api/v2/translate_tags.json b/data/api/v2/translate_tags.json index 4c6059aa05e..1e1f9ccc797 100644 --- a/data/api/v2/translate_tags.json +++ b/data/api/v2/translate_tags.json @@ -239,6 +239,10 @@ "name": "Processes", "description": "The processes API allows you to query processes data for your organization. See the [Live Processes page](https://docs.datadoghq.com/infrastructure/process/) for more information." }, + "product-analytics": { + "name": "Product Analytics", + "description": "Send server-side events to Product Analytics. Server-Side Events Ingestion allows you to collect custom events\nfrom any server-side source, and retains events for 15 months. Server-side events are helpful for understanding\ncauses of a funnel drop-off which are external to the client-side (for example, payment processing error).\nSee the [Product Analytics page](https://docs.datadoghq.com/product_analytics/) for more information." + }, "rum": { "name": "RUM", "description": "Manage your Real User Monitoring (RUM) applications, and search or aggregate your RUM events over HTTP. See the [RUM & Session Replay page](https://docs.datadoghq.com/real_user_monitoring/) for more information"