Datadog Source Code Integration

Overview

The source code integration supports:

Languages:
  • Go
  • Java
  • JavaScript (doesn't support transpiled JavaScript)
  • Python
  • .NET
  • Ruby

Git providers:
  • GitHub
  • GitLab
  • BitBucket
  • Azure DevOps

Datadog’s source code integration allows you to connect your telemetry with your Git repositories hosted in GitHub, GitLab, Bitbucket, or Azure DevOps. Once you have enabled the source code integration, you can debug stack traces, slow profiles, and other issues by quickly accessing the relevant lines of your source code.

Inline code snippet of a Java RuntimeException with a button to view the code in GitHub

Setup

Datadog Agent v7.35.0 or later is required.

If you have APM set up already, navigate to Integrations > Link Source Code and configure the source code integration for your backend services.

You can link active commits by either tagging your telemetry or embedding git information in the deployed artifact.

Tag your telemetry

To link data to a specific commit, tag your telemetry with git.commit.sha and git.repository_url tags. Ensure that the git.repository_url tag does not contain protocols. For example, if your repository URL is https://github.com/example_repo, the value for the git.repository_url tag should be github.com/example_repo.

This approach requires Docker, or containerd >= 1.5.6. It doesn't support containers running on AWS Fargate. For additional container setups, see the Host tab.

If you are running your app in containers, Datadog can extract source code information directly from your images’ Docker labels. During build time, follow the Open Containers standard to add the git commit SHA and repository URL as Docker labels:

docker build . \
  -t my-application \
  --label org.opencontainers.image.revision=$(git rev-parse HEAD) \
  --label org.opencontainers.image.source=git-provider.example/me/my-repo

If you use Kubernetes, tag your deployed pod with a pod annotation using Datadog’s Tag Autodiscovery:

ad.datadoghq.com/tags: '{"git.commit.sha": "<FULL_GIT_COMMIT_SHA>", "git.repository_url": "git-provider.example/me/my-repo"}'

The git.commit.sha and git.repository_url are tagged in your telemetry.

Datadog can extract source code information directly from your serverless application according to your Serverless Monitoring for AWS Lambda setup.

APM Serverless SetupMethod Description
Datadog Serverless Framework PluginIf you are using the Datadog Serverless Plugin to instrument your serverless application, use a serverless-plugin-datadog version >= 5.18.0.
datadog-cdk-constructsIf you are using the Datadog CDK Construct to instrument your serverless application, use a datadog-cdk-constructs version >= 0.8.5 for AWS CDK v1, and datadog-cdk-constructs-v2 version >= 1.4.0 for AWS CDK v2.
datadog-ciIf you are using the Datadog CLI client to instrument your serverless application, use a datadog-ci version >= 2.4.1. You must run the CLI tool in the same directory as the code repository.

To tag your traces, spans, and profiles with git.commit.sha and git.repository_url, configure the tracer with the DD_TAGS environment variable:

export DD_TAGS="git.commit.sha:<FULL_GIT_COMMIT_SHA>,git.repository_url:git-provider.example/me/my-repo"
./my-application start

Datadog only captures the repository URL, the commit SHA of the current branch, and a list of tracked file paths—Datadog does not ingest or store any user code.

Embed git information in your artifacts on CI

You can embed git information such as the repository URL and commit hash in your artifact. The Datadog Tracing Libraries use this information to automatically link the active commit to your APM service.

Select one of the following languages that supports embedding git information:

Go embeds version control information in binaries starting in version 1.18.

Ensure your service meets all the following requirements:

  • You are using a version of Go >= 1.18.
  • You are using a version of the Datadog Go Tracer >= 1.48.0.
  • Your application was built as a module using go.mod, and the module path is your code repository’s URL.

First, upgrade the Python tracer to v1.12 or higher.

For the standard library:

  1. Install the ddtrace package.
  2. Add import ddtrace.sourcecode.setuptools_auto as the first import to setup.py.
  3. Set the environment variable DD_MAIN_PACKAGE to the name of the primary Python package.

For the unified Python project settings file:

  1. Install the hatch-datadog-build-metadata plugin and configure it to embed git metadata. If the project already has URLs, you must reconfigure them as dynamic and move them to another config section.
  2. Set the environment variable DD_MAIN_PACKAGE to the name of the primary Python package.

Datadog can use Microsot SourceLink to extract the git commit SHA and repository URL directly from your .NET assembly. To use this approach:

  1. Open your project file (.csproj) in your IDE, and add a reference to one of the following NuGet packages, based on where your git repository is hosted:
  2. Upgrade the .NET tracer to v2.25.0 or higher
  3. Ensure that your .pdb files are deployed alongside your .NET assemblies (.dll or .exe) in the same folder.

Build inside a Docker container

If your build process is executed in CI within a Docker container, perform the following steps to ensure that the build can access git information:

  1. Add the following text to your .dockerignore file. This ensures that the build process is able to access a subset of the .git folder, enabling it to determine the git commit hash and repository URL.
!.git/HEAD
!.git/config
!.git/refs
  1. Add the following line of code to your Dockerfile. Ensure that it is placed before the actual build is ran.
COPY .git ./.git

Configure your repositories

Install Datadog’s GitHub integration on the GitHub integration tile to link your telemetry with your source code. When specifying permissions on the integration tile, enable Datadog read permissions to Contents.

By setting up the GitHub integration, you can see inline code snippets in Error Tracking. For more information, see Inline Source Code.

Self-hosted instances or private URLs are not supported.

To link telemetry to your source code, Datadog collects metadata for every commit SHA from your Git repository with the datadog-ci git-metadata upload command.

When you run datadog-ci git-metadata upload within a Git repository, Datadog receives the repository URL, the commit SHA of the current branch, and a list of tracked file paths.

Validation

To ensure the data is being collected, run datadog-ci git-metadata upload in your CI pipeline.

You can expect to see the following output:

Reporting commit 007f7f466e035b052415134600ea899693e7bb34 from repository git@github.com:my-org/my-repository.git.
180 tracked file paths will be reported.
✅  Handled in 0.077 seconds.

Usage

You can see links from stack frames to their source repository in Error Tracking.

  1. Navigate to APM > Error Tracking.
  2. Click on an issue. The Issue Details panel appears on the right.
  3. Under Latest Event, click the View button on the right of a frame or select View file, View Git blame, or View commit to be redirected to your source code management tool.
A view repository button with three options (view file, view blame, and view commit) available on the right side of an error stack trace in Error Tracking

You can see links from profile frames to their source repository in the Continuous Profiler.

  1. Navigate to APM > Profile Search.
  2. Click on a profile and hover your cursor over a method in the flamegraph. A kebab icon with the More actions label appears on the right.
  3. Click More actions > View in repo to open the trace in its source code repository.
Link to GitHub from the Continuous Profiler

Inline source code

Install Datadog’s GitHub integration to directly inline code snippets from your GitHub repository in your stack traces in Error Tracking.

Note: When specifying permissions on the integration tile, enable Datadog read permissions to Contents.

Self managed GitLab is not supported.

If you are a GitLab.com user, no setup is required to inline code snippets from your GitLab repository in your stack traces in Error Tracking.

  1. Navigate to APM > Error Tracking.
  2. Click on an issue. The Issue Details panel appears on the right.
  3. Click Connect to Preview and Authorize to access the source code snippet containing the error.
  4. Under Latest Event, click the View Code button on the right of a frame or select View file, View Git blame, or View commit to be redirected to your source code management tool.
An inline code snippet in a stack trace

Further Reading