--- title: Send Custom Pipelines to Datadog description: Datadog, the leading service for cloud-scale monitoring. breadcrumbs: >- Docs > Continuous Integration Visibility > CI Pipeline Visibility in Datadog > Send Custom Pipelines to Datadog --- > For the complete documentation index, see [llms.txt](https://docs.datadoghq.com/llms.txt). # Send Custom Pipelines to Datadog {% callout %} # Important note for users on the following Datadog sites: app.ddog-gov.com, us2.ddog-gov.com {% alert level="danger" %} This product is not supported for your selected [Datadog site](https://docs.datadoghq.com/getting_started/site.md). ({% placeholder "user-datadog-site-name" /%}). {% /alert %} {% /callout %} ## Overview{% #overview %} If your CI provider is not supported, you can send custom pipelines through HTTP using the [public API endpoint](https://docs.datadoghq.com/api/latest/ci-visibility-pipelines.md#send-pipeline-event). For more information about how pipeline executions are modeled, see [Pipeline Data Model and Execution Types](https://docs.datadoghq.com/continuous_integration/guides/pipeline_data_model.md). ### Compatibility{% #compatibility %} | Pipeline Visibility | Platform | Definition | | -------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | [Logs Analysis](https://docs.datadoghq.com/continuous_integration/guides/use_ci_jobs_failure_analysis.md) | Logs Analysis | Uses LLM models on relevant logs to analyze the root cause of failed CI jobs. | | Logs correlation | Logs correlation | Correlate pipeline and job spans to logs. Requires Logs Storage. | | [Running pipelines](https://docs.datadoghq.com/glossary.md#running-pipeline) | Running pipelines | View pipeline executions that are running. | | [Custom tags](https://docs.datadoghq.com/glossary.md#custom-tag) [and measures at runtime](https://docs.datadoghq.com/glossary.md#custom-measure) | Custom tags and measures at runtime | Configure [custom tags and measures](https://docs.datadoghq.com/continuous_integration/pipelines/custom_tags_and_measures.md?tab=linux) at runtime. | | [Manual steps](https://docs.datadoghq.com/glossary.md#manual-step) | Manual steps | View manually triggered pipelines. | | [Parameters](https://docs.datadoghq.com/glossary.md#parameter) | Parameters | Set custom parameters when a pipeline is triggered. | | [Partial retries](https://docs.datadoghq.com/glossary.md#partial-retry) | Partial pipelines | View partially retried pipeline executions. | | [Pipeline failure reasons](https://docs.datadoghq.com/glossary.md#pipeline-failure) | Pipeline failure reasons | Identify pipeline failure reasons from error messages. | | [Queue time](https://docs.datadoghq.com/glossary.md#queue-time) | Queue time | View the amount of time pipeline jobs sit in the queue before processing. | | [Filter CI Jobs on the critical path](https://docs.datadoghq.com/continuous_integration/guides/identify_highest_impact_jobs_with_critical_path.md) | Filter CI Jobs on the critical path | Filter by jobs on the critical path. | | [Execution time](https://docs.datadoghq.com/glossary.md#pipeline-execution-time) | Execution time | View the amount of time pipelines have been running jobs. | ## Configure CI Visibility{% #configure-ci-visibility %} To send pipeline events programmatically to Datadog, ensure that your [`DD_API_KEY`](https://app.datadoghq.com/organization-settings/api-keys) is configured. 1. Set the headers of your HTTP request: - `DD-API-KEY`: Your [Datadog API key](https://app.datadoghq.com/organization-settings/api-keys). - `Content-Type`: `application/json`. 1. Prepare the payload body by entering information about the [pipeline execution](https://docs.datadoghq.com/continuous_integration/guides/pipeline_data_model.md) in a cURL command: | Parameter Name | Description | Example Value | | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | | Unique ID | The UUID of the pipeline run. The ID has to be unique across retries and pipelines, including partial retries. | `b3262537-a573-44eb-b777-4c0f37912b05` | | Name | The name of the pipeline. All pipeline runs for the builds should have the same name. | `Documentation Build` | | Git Repository | The Git repository URL that triggered the pipeline. | `https://github.com/Datadog/documentation` | | Commit Author | The commit author email that triggered the pipeline. | `contributor@github.com` | | Commit SHA | The commit hash that triggered the pipeline. | `cf852e17dea14008ac83036430843a1c` | | Status | The final status of the pipeline. Allowed enum values: `success`, `error`, `canceled`, `skipped`, `blocked`, or `running`. | `success` | | Partial Retry | Whether or not the pipeline was a partial retry of a previous attempt. This field expects a boolean value (`true` or `false`). A partial retry is one which only runs a subset of the original jobs. | `false` | | Start | Time when the pipeline run started (it should not include any [queue time](https://docs.datadoghq.com/glossary.md#queue-time)). The time format must be RFC3339. | `2024-08-22T11:36:29-07:00` | | End | Time when the pipeline run finished. The time format must be RFC3339. The end time cannot be longer than 1 year after the start time. | `2024-08-22T14:36:00-07:00` | | URL | The URL to look at the pipeline in the CI provider UI. | `http://your-ci-provider.com/pipeline/{pipeline-id}` | For example, this payload sends a CI pipeline event to Datadog: ```bash curl -X POST "https://api.datadoghq.com/api/v2/ci/pipeline" \ -H "Content-Type: application/json" \ -H "DD-API-KEY: " \ -d @- << EOF { "data": { "attributes": { "provider_name": "", "resource": { "level": "pipeline", "unique_id": "b3262537-a573-44eb-b777-4c0f37912b05", "name": "Documentation Build", "git": { "repository_url": "https://github.com/Datadog/documentation", "author_email": "contributor@github.com", "sha": "cf852e17dea14008ac83036430843a1c" }, "status": "success", "start": "2024-08-22T11:36:29-07:00", "end": "2024-08-22T14:36:00-07:00", "partial_retry": false, "url": "" } }, "type": "cipipeline_resource_request" } } EOF ``` 1. After sending your pipeline event to Datadog, you can integrate additional event types such as `stage`, `job`, and `step`. For more information, see the [Send Pipeline Event endpoint](https://docs.datadoghq.com/api/latest/ci-visibility-pipelines.md#send-pipeline-event). ## Running pipelines{% #running-pipelines %} Pipeline events sent with the `status` set to `running` have the same `unique_id` as the final pipeline event. Running pipelines can be updated by adding more information while they are still running. A running pipeline consists of the following events: 1. The initial running pipeline event with the `status` set to `running`. 1. Optionally, `N` running pipeline events that update the pipeline with more information, with the same `unique_id` and the `status` set to `running`. 1. The final pipeline event **without** a `running` status and the same `unique_id`. **Note**: The most recent value may not always be the one displayed in the UI when a field is updated. For example, if the tag `my_tag` is set to `value1` in the first running pipeline, and then is updated to `value2`, you may see `value1` instead of `value2` in the UI. It is recommended to only update running pipelines by adding more fields instead modifying existing ones. ## Running jobs{% #running-jobs %} Job events can also be sent while a job is still running by setting the `status` to `running`. As with running pipelines, all events for the same job share the same `id` and `pipeline_unique_id`. A running job consists of the following events: 1. The initial running job event with the `status` set to `running`. 1. The final job event with a terminal status (such as `success` or `error`) and the same `id` and `pipeline_unique_id`. A running job event does not require an `end` time. The `end` time is set when the final job event is sent. ## Manage job logs{% #manage-job-logs %} ### Logs Analysis{% #logs-analysis %} Logs Analysis uses LLM models to classify job failures by root cause based on relevant logs coming from your CI provider. For a full explanation, see the [Logs Analysis guide](https://docs.datadoghq.com/continuous_integration/guides/use_ci_jobs_failure_analysis.md). Logs Analysis is enabled by default in Datadog, but requires job logs forwarding to be configured, as described below. In [CI/CD Optimization Repository settings](https://app.datadoghq.com/ci/settings/ci-cd/repositories), you can enable or disable Logs Analysis for your organization or individual repositories. Send log lines for a custom CI job to the [CI job logs intake API](https://docs.datadoghq.com/api/latest/ci-visibility-logs/send-ci-job-logs.md). Use identifiers that match the pipeline and job events you send through the [CI Visibility Pipelines API](https://docs.datadoghq.com/api/latest/ci-visibility-pipelines.md#send-pipeline-event). Each log object has three required fields: - `message`: The non-empty text of the log line. - `pipeline_unique_id`: Must match the pipeline event's `resource.unique_id` and the job event's `resource.pipeline_unique_id`. - `job_id`: Must match the job event's `resource.id`. All other log fields are optional. If provided, `provider_name` must match the pipeline event's `provider_name`. Datadog uses `custom` when the field is omitted from both the pipeline event and the log lines. Send log lines in batches while the job runs, or send the batches when it finishes. Datadog recommends sending all batches before submitting the completed job event. After you submit that event, Datadog closes the job log after 20 seconds without a new line. Lines received after it closes may not appear in the job's Logs tab. The following request sends one log line for a job. This example uses the US1 site; replace `datadoghq.com` with your Datadog site if needed. ```bash curl -X POST "https://http-intake.logs.datadoghq.com/api/v2/cilogs" \ -H "Content-Type: application/json" \ -H "DD-API-KEY: " \ -d @- << EOF { "message": "Running go test ./...", "pipeline_unique_id": "b3262537-a573-44eb-b777-4c0f37912b05", "job_id": "job-456", "provider_name": "" } EOF ``` A request can contain one log object or an array of up to 1,000 log objects, with an uncompressed body of up to 5.1 MiB. For compression, retry guidance, optional attributes, and per-job limits, see the [Send CI job logs API reference](https://docs.datadoghq.com/api/latest/ci-visibility-logs/send-ci-job-logs.md). ### Logs Storage{% #logs-storage %} After setting up job log delivery as described in Logs Analysis, go to [CI/CD Optimization Repository settings](https://app.datadoghq.com/ci/settings/ci-cd/repositories) and enable Logs Storage for your organization or individual repositories. Stored logs appear in the Logs tab for the job. Logs Storage is billed separately from CI Visibility. Configure log retention, exclusion filters, and indexes in [Log Management](https://docs.datadoghq.com/logs.md). ## Visualize pipeline data in Datadog{% #visualize-pipeline-data-in-datadog %} The [**CI Pipeline List**](https://app.datadoghq.com/ci/pipelines) and [**Executions**](https://app.datadoghq.com/ci/pipeline-executions) pages populate with data after the pipelines are accepted for processing. The **CI Pipeline List** page shows data for only the default branch of each repository. For more information, see [Search and Manage CI Pipelines](https://docs.datadoghq.com/continuous_integration/search.md#search-for-pipelines). ## Further reading{% #further-reading %} Additional helpful documentation, links, and articles: - [Explore Pipeline Execution Results and Performance](https://docs.datadoghq.com/continuous_integration/pipelines.md) - [Learn about the Pipeline Data Model and Execution Types](https://docs.datadoghq.com/continuous_integration/guides/pipeline_data_model.md) - [Troubleshooting CI Visibility](https://docs.datadoghq.com/continuous_integration/troubleshooting.md)