Documentation
Datadog Tracer
Integrations
ddtrace/tracer

ddtrace/tracer

Those integrations are enabled by having the following import in the project’s orchestrion.tool.go file:

import (
	_ "github.com/DataDog/orchestrion"

	_ "github.com/DataDog/dd-trace-go/v2/ddtrace/tracer" // integration
	//...
)

github.com/DataDog/dd-trace-go/v2/ddtrace/tracer

Automatically starts the github.com/DataDog/dd-trace-go/v2/ddtrace/tracer at the start of the application, and closes it at exit of the main function.

Adding the //dd:span directive on functions creates custom spans representing every call to that function. The default operation (span) name is the name of the function, and this can be overridden using a "span.name" argument to the directive:

//dd:span span.name:custom-operation-name other:tag
func myFunction() {
  // The default operation name would have been "myFunction"
}

Function literal expressions don't have a function name, and their default operation name is the value of the very first directive argument (if there is one). If there are no directive arguments, the operation name will remain blank.

//dd:span other:tag span.name:custom-operation-name
myOp := func() {
  // The default operation name would have been "tag"
}

__dd_gls_v2

Join Point
Definition of runtime.g
Advice
Add new field __dd_gls_v2 of type any.
Advice
Add blank import of unsafe
Advice
Introduce new declarations:
//go:linkname __dd_orchestrion_gls_get __dd_orchestrion_gls_get.V2
var __dd_orchestrion_gls_get = func() any {
	return getg().m.curg.__dd_gls_v2
}

//go:linkname __dd_orchestrion_gls_set __dd_orchestrion_gls_set.V2
var __dd_orchestrion_gls_set = func(val any) {
	getg().m.curg.__dd_gls_v2 = val
}

goexit1

Join Point
All of
  • Import path runtime
  • Function body
    • Function declaration
      • Function name goexit1
Advice
Prepend statements produced by the following template:
getg().__dd_gls_v2 = nil

dyngo operation GLS field

Join Point
Definition of dyngo.operation
Advice
Add new field __dd_glsPop of type orchestrion.GLSPopperCell.

dyngo RegisterOperation GLS push

Join Point
All of
Advice
Prepend statements produced by the following template:
// Using the following synthetic imports:
import (
	orchestrion "github.com/DataDog/dd-trace-go/v2/internal/orchestrion"
)
{{- $ctx := .Function.Argument 0 -}}
{{- $op := .Function.Argument 1 -}}
{
	// GLSActivate (ctxp non-nil) wraps the parent so the returned
	// context is GLS-aware (matching in-source CtxWithValue), pushes
	// the op, and captures the first-wins popper onto __dd_glsPop.
	__dd_o := {{ $op }}.unwrap()
	orchestrion.GLSActivate(&{{ $ctx }}, contextKey{}, {{ $op }}, &__dd_o.__dd_glsPop, nil)
}

dyngo FromContext GLS read

Join Point
All of
Advice
Prepend statements produced by the following template:
// Using the following synthetic imports:
import (
	orchestrion "github.com/DataDog/dd-trace-go/v2/internal/orchestrion"
)
{{- $ctx := .Function.Argument 0 -}}
// Wrap unconditionally: AppSec calls FromContext(nil) from
// un-instrumented sites (e.g. contrib/os: dyngo.FromContext(nil)),
// relying solely on the GLS fallback. WrapContext(nil) returns a
// glsContext over context.Background when orchestrion is enabled, so
// the read below still consults the GLS. A nil-guard here would let
// the source's `if ctx == nil { return }` short-circuit before the
// GLS is ever read. Matches in-source FromContext (orchestrion#782).
{{ $ctx }} = orchestrion.WrapContext({{ $ctx }})

dyngo FinishOperation GLS deactivate

Join Point
All of
Advice
Prepend statements produced by the following template:
// Using the following synthetic imports:
import (
	orchestrion "github.com/DataDog/dd-trace-go/v2/internal/orchestrion"
)
{{- $op := .Function.Argument 0 -}}
defer func() {
	__dd_o := {{ $op }}.unwrap()
	orchestrion.GLSDeactivate(nil, &__dd_o.__dd_glsPop)
}()

func main()

Join Point
All of
  • Package name main
  • Is test main false
  • Function body
    • Function declaration
      • Function name main
      • Signature matches
        • Arguments None
        • Results None
Advice
Introduce new declarations:
// Using the following synthetic imports:
import (
	tracer "github.com/DataDog/dd-trace-go/v2/ddtrace/tracer"
)
func init() { tracer.Start() }
Advice
Prepend statements produced by the following template:
// Using the following synthetic imports:
import (
	tracer "github.com/DataDog/dd-trace-go/v2/ddtrace/tracer"
)
defer tracer.Stop()

//dd:span

Join Point
Function body
  • Has directive //dd:span
Advice
Prepend statements produced by the following template:
// Using the following synthetic imports:
import (
	context "context"
	tracer "github.com/DataDog/dd-trace-go/v2/ddtrace/tracer"
)
{{- $ctx := .Function.ArgumentOfType "context.Context" -}}
{{- $req := .Function.ArgumentOfType "*net/http.Request" -}}
{{- if eq $ctx "" -}}
	{{- $impl := .Function.ArgumentThatImplements "context.Context" -}}
	{{- if ne $impl "" -}}
		{{- if eq $impl "ctx" -}}
			{{- $ctx = "__dd_span_ctx" -}}
	var __dd_span_ctx context.Context
	if ctx != nil {
		__dd_span_ctx = ctx
	} else {
		__dd_span_ctx = context.TODO()
	}
		{{- else -}}
			{{- $ctx = "ctx" -}}
	__dd_ctxImpl := {{ $impl }}
	var ctx context.Context
	if __dd_ctxImpl != nil {
		ctx = __dd_ctxImpl
	} else {
		ctx = context.TODO()
	}
		{{- end -}}
	{{- else if ne $req "" -}}
		{{- $ctx = "ctx" -}}
	ctx := {{ $req }}.Context()
	{{- else -}}
		{{- $ctx = "ctx" -}}
	ctx := context.TODO()
	{{- end }}
{{ end -}}

{{ $functionName := .Function.Name -}}
{{- $opName := $functionName -}}
{{- range .DirectiveArgs "dd:span" -}}
	{{- if eq $opName "" -}}
		{{ $opName = .Value }}
	{{- end -}}
	{{- if eq .Key "span.name" -}}
		{{- $opName = .Value -}}
		{{- break -}}
	{{- end -}}
{{- end -}}

var span *tracer.Span
span, {{ $ctx }} = tracer.StartSpanFromContext({{ $ctx }}, {{ printf "%q" $opName }},
	{{- with $functionName }}
		tracer.Tag("function-name", {{ printf "%q" $functionName }}),
	{{ end -}}
	{{- range .DirectiveArgs "dd:span" }}
		{{ if eq .Key "span.name" -}}{{- continue -}}{{- end -}}
		tracer.Tag({{ printf "%q" .Key }}, {{ printf "%q" .Value }}),
	{{- end }}
)
{{- with $req }}
	{{ $req }} = {{ $req }}.WithContext({{ $ctx }})
{{- end }}

{{ with .Function.ResultOfType "error" -}}
	defer func(){
		span.Finish(tracer.WithError({{ . }}))
	}()
{{ else -}}
	defer span.Finish()
{{- end -}}

Span GLS fields

Join Point
Definition of tracer.Span
Advice
Add new field __dd_glsPop of type orchestrion.GLSPopperCell.
Advice
Add new field __dd_glsDone of type orchestrion.GLSDoneCell.

Span ContextWithSpan GLS push

Join Point
All of
Advice
Prepend statements produced by the following template:
// Using the following synthetic imports:
import (
	internal "github.com/DataDog/dd-trace-go/v2/internal"
	orchestrion "github.com/DataDog/dd-trace-go/v2/internal/orchestrion"
)
{{- $s := .Function.Argument 1 -}}
if {{ $s }} != nil {
	orchestrion.GLSActivate(nil, internal.ActiveSpanKey, {{ $s }}, &{{ $s }}.__dd_glsPop, &{{ $s }}.__dd_glsDone)
}

Span SpanFromContext GLS read

Join Point
All of
Advice
Prepend statements produced by the following template:
// Using the following synthetic imports:
import (
	orchestrion "github.com/DataDog/dd-trace-go/v2/internal/orchestrion"
)
{{- $ctx := .Function.Argument 0 -}}
if {{ $ctx }} != nil {
	{{ $ctx }} = orchestrion.WrapContext({{ $ctx }})
}

Span Finish GLS deactivate

Join Point
Function body
  • Function declaration
Advice
Prepend statements produced by the following template:
// Using the following synthetic imports:
import (
	orchestrion "github.com/DataDog/dd-trace-go/v2/internal/orchestrion"
)
{{- $s := .Function.Receiver -}}
if {{ $s }} != nil {
	orchestrion.GLSDeactivate(&{{ $s }}.__dd_glsDone, &{{ $s }}.__dd_glsPop)
}

Span clear GLS reset

Join Point
Function body
  • Function declaration
Advice
Prepend statements produced by the following template:
// Using the following synthetic imports:
import (
	orchestrion "github.com/DataDog/dd-trace-go/v2/internal/orchestrion"
)
{{- $s := .Function.Receiver -}}
orchestrion.GLSReset(&{{ $s }}.__dd_glsDone, &{{ $s }}.__dd_glsPop)

github.com/DataDog/dd-trace-go/v2/internal/orchestrion

Operations that interact with Go's runtime system.

__dd_gls_v2

Join Point
Definition of runtime.g
Advice
Add new field __dd_gls_v2 of type any.
Advice
Add blank import of unsafe
Advice
Introduce new declarations:
//go:linkname __dd_orchestrion_gls_get __dd_orchestrion_gls_get.V2
var __dd_orchestrion_gls_get = func() any {
	return getg().m.curg.__dd_gls_v2
}

//go:linkname __dd_orchestrion_gls_set __dd_orchestrion_gls_set.V2
var __dd_orchestrion_gls_set = func(val any) {
	getg().m.curg.__dd_gls_v2 = val
}

goexit1

Join Point
All of
  • Import path runtime
  • Function body
    • Function declaration
      • Function name goexit1
Advice
Prepend statements produced by the following template:
getg().__dd_gls_v2 = nil

dyngo operation GLS field

Join Point
Definition of dyngo.operation
Advice
Add new field __dd_glsPop of type orchestrion.GLSPopperCell.

dyngo RegisterOperation GLS push

Join Point
All of
Advice
Prepend statements produced by the following template:
// Using the following synthetic imports:
import (
	orchestrion "github.com/DataDog/dd-trace-go/v2/internal/orchestrion"
)
{{- $ctx := .Function.Argument 0 -}}
{{- $op := .Function.Argument 1 -}}
{
	// GLSActivate (ctxp non-nil) wraps the parent so the returned
	// context is GLS-aware (matching in-source CtxWithValue), pushes
	// the op, and captures the first-wins popper onto __dd_glsPop.
	__dd_o := {{ $op }}.unwrap()
	orchestrion.GLSActivate(&{{ $ctx }}, contextKey{}, {{ $op }}, &__dd_o.__dd_glsPop, nil)
}

dyngo FromContext GLS read

Join Point
All of
Advice
Prepend statements produced by the following template:
// Using the following synthetic imports:
import (
	orchestrion "github.com/DataDog/dd-trace-go/v2/internal/orchestrion"
)
{{- $ctx := .Function.Argument 0 -}}
// Wrap unconditionally: AppSec calls FromContext(nil) from
// un-instrumented sites (e.g. contrib/os: dyngo.FromContext(nil)),
// relying solely on the GLS fallback. WrapContext(nil) returns a
// glsContext over context.Background when orchestrion is enabled, so
// the read below still consults the GLS. A nil-guard here would let
// the source's `if ctx == nil { return }` short-circuit before the
// GLS is ever read. Matches in-source FromContext (orchestrion#782).
{{ $ctx }} = orchestrion.WrapContext({{ $ctx }})

dyngo FinishOperation GLS deactivate

Join Point
All of
Advice
Prepend statements produced by the following template:
// Using the following synthetic imports:
import (
	orchestrion "github.com/DataDog/dd-trace-go/v2/internal/orchestrion"
)
{{- $op := .Function.Argument 0 -}}
defer func() {
	__dd_o := {{ $op }}.unwrap()
	orchestrion.GLSDeactivate(nil, &__dd_o.__dd_glsPop)
}()
contrib/valyala/fasthttpinternal/civisibility/integrations/gotesting