Skip to content

[APM Go] fix and clarify dd-trace-go v2 docs for release #28292

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 32 commits into from
Jun 5, 2025
Merged

[APM Go] fix and clarify dd-trace-go v2 docs for release #28292

Show file tree
Hide file tree
Changes from 7 commits
Commits
Show all changes
32 commits
Select commit Hold shift + click to select a range
3b0dbd6
fix mgo link
hannahkm Mar 21, 2025
0655d5d
add ref to migration page for pages mentioning v2
hannahkm Mar 21, 2025
babc34a
move text and add link for more clarity
hannahkm Mar 21, 2025
553a102
Put common message in reuse shortcode.
brett0000FF Mar 25, 2025
dcace93
Replace mention of in Preview. Use reuse shortcode for most content.
brett0000FF Mar 26, 2025
cb0ae0f
Put v2 tabs first.
brett0000FF Mar 26, 2025
baa2852
Improve migration guide.
brett0000FF Mar 26, 2025
4677b88
remove imports to v1 entirely for GA
hannahkm Apr 2, 2025
d02f08d
move v2 references before v1
hannahkm Apr 2, 2025
fbef9fd
update profiling page
hannahkm Apr 2, 2025
f5586ef
fix some documentation
hannahkm Apr 7, 2025
34c2b20
update migration page with shim
hannahkm Apr 7, 2025
0c57021
add details about api changes (child spans)
hannahkm Apr 7, 2025
389c999
Fix instances where shortcode doesn't render link.
brett0000FF Apr 7, 2025
633dce4
rename v2check to v2fix
hannahkm Apr 7, 2025
bf7b620
add info about -fix flag
hannahkm Apr 8, 2025
a0991c3
Merge branch 'master' into hannahkm/clarify-v2-docs
hannahkm Apr 8, 2025
7372418
fix(tracing/trace_collection/compatibility): update Go tracer version…
darccio Jun 2, 2025
0811752
fix(tracing/trace_collection/custom_instrumentation/go): rename secti…
darccio Jun 2, 2025
f19b180
fix(tracing/trace_collection/compatibility/go): remove duplicated sec…
darccio Jun 2, 2025
c62b082
fix(tracing/trace_collection/custom_instrumentation/go): update migra…
darccio Jun 2, 2025
97762d1
Merge branch 'master' into hannahkm/clarify-v2-docs
darccio Jun 2, 2025
3c9d965
fix(tracing): correct references for DogStatsD address options in Go …
darccio Jun 4, 2025
2ea4d24
fix(tracing/trace_collection/custom_instrumentation/go): update span …
darccio Jun 4, 2025
c99a948
Update content/en/tracing/trace_collection/custom_instrumentation/go/…
hannahkm Jun 4, 2025
dfee6ca
Update content/en/tracing/trace_collection/custom_instrumentation/go/…
hannahkm Jun 4, 2025
60524cb
Update content/en/tracing/trace_collection/custom_instrumentation/go/…
hannahkm Jun 4, 2025
8a6beac
Apply suggestions from code review
hannahkm Jun 4, 2025
82bf284
minor edits in migration guide
hannahkm Jun 4, 2025
217ebce
Merge remote-tracking branch 'origin' into hannahkm/clarify-v2-docs
hannahkm Jun 5, 2025
0dd3214
Apply suggestions from code review
brett0000FF Jun 5, 2025
5602e3b
Remove outdated support details for v1 of the Go tracer in migration …
darccio Jun 5, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion content/en/containers/amazon_ecs/apm.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -214,7 +214,7 @@ Update the Task Definition's `entryPoint` with the following, substituting your
```

#### Code
You can alternatively update your code to have the tracer set the hostname explicitly:
You can alternatively update your code to have the tracer set the hostname explicitly. {{% tracing-go-v2 %}}

```go
package main
Expand Down
2 changes: 2 additions & 0 deletions content/en/containers/docker/apm.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -277,6 +277,8 @@ end

{{< programming-lang lang="go" >}}

{{% tracing-go-v2 %}}

```go
package main

Expand Down
2 changes: 1 addition & 1 deletion content/en/data_streams/go.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ The following instrumentation types are available:

### Prerequisites

To start with Data Streams Monitoring, you need recent versions of the Datadog Agent and Data Streams Monitoring libraries:
To start with Data Streams Monitoring, you need recent versions of the Datadog Agent and Data Streams Monitoring libraries. {{% tracing-go-v2 %}} Data Streams Monitoring has not been changed between v1 and v2 of the tracer.

* [Datadog Agent v7.34.0 or later][1]
* [dd-trace-go v1.56.1 or later][2]
Expand Down
2 changes: 1 addition & 1 deletion content/en/database_monitoring/connect_dbm_and_apm.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -110,7 +110,7 @@ Datadog recommends setting the obfuscation mode to `obfuscate_and_normalize` for
{{< tabs >}}
{{% tab "Go" %}}

Update your app dependencies to include [[email protected]][1] or greater:
Update your app dependencies to include [[email protected]][1] or greater. {{% tracing-go-v2 %}}
```shell
go get gopkg.in/DataDog/[email protected] # 1.x
# go get github.com/DataDog/dd-trace-go/v2 # 2.x
Expand Down
2 changes: 1 addition & 1 deletion content/en/opentelemetry/instrument/instrumentation_libraries.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -185,7 +185,7 @@ if __name__ == "__main__":

## Compatibility requirements

The Datadog SDK for Go supports library instrumentations written using the [Opentelemetry-Go Trace API][21], including the [`opentelemetry-go-contrib/instrumentation`][22] libraries.
The Datadog SDK for Go supports library instrumentations written using the [Opentelemetry-Go Trace API][21], including the [`opentelemetry-go-contrib/instrumentation`][22] libraries. {{% tracing-go-v2 %}} OpenTelemetry support has not changed between v1 and v2 of the Go Tracer.

## Setup

Expand Down
5 changes: 3 additions & 2 deletions content/en/security/application_security/threats/add-user-info.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -118,7 +118,7 @@ For information and options, read [the .NET tracer documentation][1].

The Go tracer package provides the `SetUser()` function, which allows you to monitor authenticated requests by adding user information to the trace. For more options, see [the Go tracer documentation][1] (or [v2 documentation][2]).

This example shows how to retrieve the current tracer span, use it to set user monitoring tags, and enable user blocking capability:
This example shows how to retrieve the current tracer span, use it to set user monitoring tags, and enable user blocking capability. {{% tracing-go-v2 %}}

```go
import (
Expand All @@ -137,6 +137,7 @@ func handler(w http.ResponseWriter, r *http.Request) {

[1]: https://pkg.go.dev/gopkg.in/DataDog/dd-trace-go.v1/ddtrace/tracer#SetUser
[2]: https://pkg.go.dev/github.com/DataDog/dd-trace-go/v2/ddtrace/tracer#SetUser

{{< /programming-lang >}}

{{< programming-lang lang="ruby" >}}
Expand Down Expand Up @@ -475,7 +476,7 @@ void OnUserSignupComplete(string userId, ...)

Starting in dd-trace-go v1.47.0, you can use the Go tracer's API to track user events.

The following examples show how to track login events or custom events (using signup as an example).
The following examples show how to track login events or custom events (using signup as an example). {{% tracing-go-v2 %}}

{{< tabs >}}
{{% tab "Login success" %}}
Expand Down
88 changes: 46 additions & 42 deletions content/en/security/application_security/threats/setup/compatibility/go.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -50,24 +50,27 @@ The Go tracer includes support for the following frameworks, data stores and lib

The Go packages listed in this page are relevant for Application Security capabilities. You can also find more tracing integrations in [APM's tracing compatibility page][16].

{{% tracing-go-v2 %}}

Supported packages have changed between v1 and v2 of the Go tracer.

{{% tabs %}}
{{% tab "v1" %}}
{{% tab "v2" %}}

**Note**: The [Go integrations documentation][6] provides a detailed overview of the supported packages and their APIs, along with usage examples.
**Note**: The [Go integrations documentation][19] provides a detailed overview of the supported packages and their APIs, along with usage examples.

<div class="alert alert-info">If you don't see your library of choice listed, fill out <a href="https://forms.gle/gHrxGQMEnAobukfn7">this form to send details</a>.</div>

### Web framework compatibility

| Framework | Threat Detection supported? | Threat Protection supported? |
|-------------------|-----------------------------|------------------------------|
| [net/http][13] | <i class="icon-check-bold"></i> | <i class="icon-check-bold"></i> |
| [Gin][7] | <i class="icon-check-bold"></i> | <i class="icon-check-bold"></i> |
| [Gorilla Mux][8] | <i class="icon-check-bold"></i> | <i class="icon-check-bold"></i> |
| [gRPC][11] | <i class="icon-check-bold"></i> | <i class="icon-check-bold"></i> |
| [echo v4][9] | <i class="icon-check-bold"></i> | <i class="icon-check-bold"></i> |
| [echo v3][10] | <i class="icon-check-bold"></i> | <i class="icon-check-bold"></i> |
| [chi][12] | <i class="icon-check-bold"></i> | <i class="icon-check-bold"></i> |
| [net/http][25] | <i class="icon-check-bold"></i> | <i class="icon-check-bold"></i> |
| [Gin][20] | <i class="icon-check-bold"></i> | <i class="icon-check-bold"></i> |
| [Gorilla Mux][21] | <i class="icon-check-bold"></i> | <i class="icon-check-bold"></i> |
| [gRPC][23] | <i class="icon-check-bold"></i> | <i class="icon-check-bold"></i> |
| [echo v4][22] | <i class="icon-check-bold"></i> | <i class="icon-check-bold"></i> |
| [chi][24] | <i class="icon-check-bold"></i> | <i class="icon-check-bold"></i> |
| [graphql-go][17] | <i class="icon-check-bold"></i> | <i class="icon-check-bold"></i> |
| [gqlgen][18] | <i class="icon-check-bold"></i> | <i class="icon-check-bold"></i> |

Expand All @@ -76,45 +79,44 @@ The Go packages listed in this page are relevant for Application Security capabi

| Framework | Threat Detection supported? | Threat Protection supported? |
|-----------------------|-----------------------------|------------------------------|
| [gRPC client][11] | <i class="icon-check-bold"></i> | <i class="icon-check-bold"></i> |
| [net/http client][13] | <i class="icon-check-bold"></i> | <i class="icon-check-bold"></i> |
| [gRPC client][23] | <i class="icon-check-bold"></i> | <i class="icon-check-bold"></i> |
| [net/http client][25] | <i class="icon-check-bold"></i> | <i class="icon-check-bold"></i> |

### Data store compatibility

| Framework | Threat Detection supported? | Threat Protection supported? |
|-------------------|-----------------|--------------------------------------------------------------------------|
| [sql][14] | <i class="icon-check-bold"></i> | <i class="icon-check-bold"></i> |
| [sql][26] | <i class="icon-check-bold"></i> | <i class="icon-check-bold"></i> |

[6]: https://pkg.go.dev/gopkg.in/DataDog/dd-trace-go.v1/contrib
[7]: https://pkg.go.dev/gopkg.in/DataDog/dd-trace-go.v1/contrib/gin-gonic/gin
[8]: https://pkg.go.dev/gopkg.in/DataDog/dd-trace-go.v1/contrib/gorilla/mux
[9]: https://pkg.go.dev/gopkg.in/DataDog/dd-trace-go.v1/contrib/labstack/echo.v4
[10]: https://pkg.go.dev/gopkg.in/DataDog/dd-trace-go.v1/contrib/labstack/echo
[11]: https://pkg.go.dev/gopkg.in/DataDog/dd-trace-go.v1/contrib/google.golang.org/grpc
[12]: https://pkg.go.dev/gopkg.in/DataDog/dd-trace-go.v1/contrib/go-chi/chi
[13]: https://pkg.go.dev/gopkg.in/DataDog/dd-trace-go.v1/contrib/net/http
[14]: https://pkg.go.dev/gopkg.in/DataDog/dd-trace-go.v1/contrib/database/sql
[16]: /tracing/compatibility_requirements/go
[17]: https://pkg.go.dev/github.com/graphql-go/graphql
[18]: https://pkg.go.dev/github.com/99designs/gqlgen/graphql
[19]: https://pkg.go.dev/github.com/DataDog/dd-trace-go/v2/contrib
[20]: https://pkg.go.dev/github.com/DataDog/dd-trace-go/contrib/gin-gonic/gin/v2
[21]: https://pkg.go.dev/github.com/DataDog/dd-trace-go/contrib/gorilla/mux/v2
[22]: https://pkg.go.dev/github.com/DataDog/dd-trace-go/contrib/labstack/echo.v4/v2
[23]: https://pkg.go.dev/github.com/DataDog/dd-trace-go/contrib/google.golang.org/grpc/v2
[24]: https://pkg.go.dev/github.com/DataDog/dd-trace-go/contrib/go-chi/chi/v2
[25]: https://pkg.go.dev/github.com/DataDog/dd-trace-go/contrib/net/http/v2
[26]: https://pkg.go.dev/github.com/DataDog/dd-trace-go/contrib/database/sql/v2

{{% /tab %}}
{{% tab "v2" %}}
{{% tab "v1" %}}

**Note**: The [Go integrations documentation][19] provides a detailed overview of the supported packages and their APIs, along with usage examples.
**Note**: The [Go integrations documentation][6] provides a detailed overview of the supported packages and their APIs, along with usage examples.

<div class="alert alert-info">If you don't see your library of choice listed, fill out <a href="https://forms.gle/gHrxGQMEnAobukfn7">this form to send details</a>.</div>

### Web framework compatibility

| Framework | Threat Detection supported? | Threat Protection supported? |
|-------------------|-----------------------------|------------------------------|
| [net/http][25] | <i class="icon-check-bold"></i> | <i class="icon-check-bold"></i> |
| [Gin][20] | <i class="icon-check-bold"></i> | <i class="icon-check-bold"></i> |
| [Gorilla Mux][21] | <i class="icon-check-bold"></i> | <i class="icon-check-bold"></i> |
| [gRPC][23] | <i class="icon-check-bold"></i> | <i class="icon-check-bold"></i> |
| [echo v4][22] | <i class="icon-check-bold"></i> | <i class="icon-check-bold"></i> |
| [chi][24] | <i class="icon-check-bold"></i> | <i class="icon-check-bold"></i> |
| [net/http][13] | <i class="icon-check-bold"></i> | <i class="icon-check-bold"></i> |
| [Gin][7] | <i class="icon-check-bold"></i> | <i class="icon-check-bold"></i> |
| [Gorilla Mux][8] | <i class="icon-check-bold"></i> | <i class="icon-check-bold"></i> |
| [gRPC][11] | <i class="icon-check-bold"></i> | <i class="icon-check-bold"></i> |
| [echo v4][9] | <i class="icon-check-bold"></i> | <i class="icon-check-bold"></i> |
| [echo v3][10] | <i class="icon-check-bold"></i> | <i class="icon-check-bold"></i> |
| [chi][12] | <i class="icon-check-bold"></i> | <i class="icon-check-bold"></i> |
| [graphql-go][17] | <i class="icon-check-bold"></i> | <i class="icon-check-bold"></i> |
| [gqlgen][18] | <i class="icon-check-bold"></i> | <i class="icon-check-bold"></i> |

Expand All @@ -123,25 +125,26 @@ The Go packages listed in this page are relevant for Application Security capabi

| Framework | Threat Detection supported? | Threat Protection supported? |
|-----------------------|-----------------------------|------------------------------|
| [gRPC client][23] | <i class="icon-check-bold"></i> | <i class="icon-check-bold"></i> |
| [net/http client][25] | <i class="icon-check-bold"></i> | <i class="icon-check-bold"></i> |
| [gRPC client][11] | <i class="icon-check-bold"></i> | <i class="icon-check-bold"></i> |
| [net/http client][13] | <i class="icon-check-bold"></i> | <i class="icon-check-bold"></i> |

### Data store compatibility

| Framework | Threat Detection supported? | Threat Protection supported? |
|-------------------|-----------------|--------------------------------------------------------------------------|
| [sql][26] | <i class="icon-check-bold"></i> | <i class="icon-check-bold"></i> |
| [sql][14] | <i class="icon-check-bold"></i> | <i class="icon-check-bold"></i> |

[6]: https://pkg.go.dev/gopkg.in/DataDog/dd-trace-go.v1/contrib
[7]: https://pkg.go.dev/gopkg.in/DataDog/dd-trace-go.v1/contrib/gin-gonic/gin
[8]: https://pkg.go.dev/gopkg.in/DataDog/dd-trace-go.v1/contrib/gorilla/mux
[9]: https://pkg.go.dev/gopkg.in/DataDog/dd-trace-go.v1/contrib/labstack/echo.v4
[10]: https://pkg.go.dev/gopkg.in/DataDog/dd-trace-go.v1/contrib/labstack/echo
[11]: https://pkg.go.dev/gopkg.in/DataDog/dd-trace-go.v1/contrib/google.golang.org/grpc
[12]: https://pkg.go.dev/gopkg.in/DataDog/dd-trace-go.v1/contrib/go-chi/chi
[13]: https://pkg.go.dev/gopkg.in/DataDog/dd-trace-go.v1/contrib/net/http
[14]: https://pkg.go.dev/gopkg.in/DataDog/dd-trace-go.v1/contrib/database/sql
[17]: https://pkg.go.dev/github.com/graphql-go/graphql
[18]: https://pkg.go.dev/github.com/99designs/gqlgen/graphql
[19]: https://pkg.go.dev/github.com/DataDog/dd-trace-go/v2/contrib
[20]: https://pkg.go.dev/github.com/DataDog/dd-trace-go/contrib/gin-gonic/gin/v2
[21]: https://pkg.go.dev/github.com/DataDog/dd-trace-go/contrib/gorilla/mux/v2
[22]: https://pkg.go.dev/github.com/DataDog/dd-trace-go/contrib/labstack/echo.v4/v2
[23]: https://pkg.go.dev/github.com/DataDog/dd-trace-go/contrib/google.golang.org/grpc/v2
[24]: https://pkg.go.dev/github.com/DataDog/dd-trace-go/contrib/go-chi/chi/v2
[25]: https://pkg.go.dev/github.com/DataDog/dd-trace-go/contrib/net/http/v2
[26]: https://pkg.go.dev/github.com/DataDog/dd-trace-go/contrib/database/sql/v2

{{% /tab %}}
{{% /tabs %}}
Expand All @@ -151,4 +154,5 @@ The Go packages listed in this page are relevant for Application Security capabi
[3]: https://github.com/DataDog/dd-trace-go#support-policy
[4]: https://github.com/DataDog/dd-trace-go#support-maintenance
[5]: https://www.datadoghq.com/support/
[15]: https://github.com/golang/go/wiki/cgo
[15]: https://github.com/golang/go/wiki/cgo
[16]: /tracing/compatibility_requirements/go
4 changes: 2 additions & 2 deletions content/en/security/application_security/threats/setup/threat_detection/go.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,7 @@ You can monitor application security for Go apps running in Docker, Kubernetes,
## Enabling threat detection
### Get started

1. **Add to your program's go.mod dependencies** the latest version of the Datadog Go library (version 1.53.0 or later):
1. **Add to your program's go.mod dependencies** the latest version of the Datadog Go library (version 1.53.0 or later). {{% tracing-go-v2 %}}

```shell
$ go get -v -u gopkg.in/DataDog/dd-trace-go.v1 # v1
Expand Down Expand Up @@ -121,4 +121,4 @@ Update your application's ECS task definition JSON file, by adding this in the e
{{< partial name="whats-next/whats-next.html" >}}

[1]: /security/application_security/threats/setup/compatibility/go/#web-framework-compatibility
[2]: /security/application_security/threats/setup/compatibility/go/
[2]: /security/application_security/threats/setup/compatibility/go/
15 changes: 9 additions & 6 deletions content/en/security/application_security/troubleshooting.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -189,13 +189,15 @@ There are no required integrations for PHP.
{{< /programming-lang >}}
{{< programming-lang lang="go" >}}

The following Go frameworks should be instrumented using the out-of-the-box APM integrations:
The following Go frameworks should be instrumented using the out-of-the-box APM integrations.

- [gRPC][2] ([v2][8])
- [net/http][3] ([v2][9])
- [Gorilla Mux][4] ([v2][10])
- [Echo][5] ([v2][11])
- [Chi][6] ([v2][12])
{{% tracing-go-v2 %}}

- [gRPC][8] ([v1][2])
- [net/http][9] ([v1][3])
- [Gorilla Mux][10] ([v1][4])
- [Echo][11] ([v1][5])
- [Chi][12] ([v1][6])

Please be sure to reference the docs appropriate for your version (v1.x or v2.x) of the Go Tracer. If your framework is not supported, [create a new issue][7] in the Go repository.

Expand All @@ -210,6 +212,7 @@ Please be sure to reference the docs appropriate for your version (v1.x or v2.x)
[10]: https://pkg.go.dev/github.com/DataDog/dd-trace-go/contrib/gorilla/mux/v2
[11]: https://pkg.go.dev/github.com/DataDog/dd-trace-go/contrib/labstack/echo.v4/v2
[12]: https://pkg.go.dev/github.com/DataDog/dd-trace-go/contrib/go-chi/chi.v5/v2
[13]: /tracing/trace_collection/custom_instrumentation/go/migration

{{< /programming-lang >}}
{{< programming-lang lang="Node.js" >}}
Expand Down
Loading
Loading