### Aspect Configuration Example with Ordering and Namespaces

Source: https://github.com/datadog/orchestrion/blob/main/_docs/content/adr/0002-aspect-application-order.md

Demonstrates how to configure aspects with specific execution orders and namespaces for fine-grained control over advice application.

```yaml
aspects:
  - id: Error Processing
    advice:
      - prepend-statements:
          namespace: "error-handling"
          order: 10  # Execute first within namespace
          template: |
            defer func() {
              __result__0 = errortrace.Wrap(__result__0)
            }()

  - id: Span Creation
    advice:
      - prepend-statements:
          namespace: "tracing"
          order: 20  # Execute after error handling
          template: |
            span := tracer.StartSpan()
            defer func() {
              span.Finish(tracer.WithError(__result__0))
            }()
```

--------------------------------

### Install Orchestrion Tool

Source: https://github.com/datadog/orchestrion/blob/main/_docs/content/docs/getting-started.md

Install Orchestrion as a project tool dependency using `go install`. Ensure the `GOBIN` directory is in your PATH if necessary.

```bash
$ go install github.com/DataDog/orchestrion@latest
```

```bash
$ export PATH="$PATH:$(go env GOBIN)"
```

--------------------------------

### New E2E Test File Example

Source: https://github.com/datadog/orchestrion/blob/main/test/e2e/README.md

A basic Go test file structure for an E2E test. It includes the necessary build tag, package declaration, imports for testing and helpers, and a sample test function that skips in short mode and utilizes helper functions.

```go
//go:build e2e

package main_test

import (
	testing
	helpers "github.com/DataDog/orchestrion/test/e2e"
)

func TestMyTest(t *testing.T) {
	if testing.Short() {
		t.Skip("Skipping e2e test in short mode")
	}

	orchestrionBin := helpers.FindOrchestrionBinary(t)
	workDir := helpers.CreateWorkDir(t, ".")

	// Your test logic using helpers
}
```

--------------------------------

### Template Declaring Go Language Level

Source: https://github.com/datadog/orchestrion/blob/main/_docs/content/contributing/aspects/code-templates.md

Illustrates setting a minimum Go language level for a template to enable the use of newer language features like generics. This example declares `go1.18`.

```yaml
lang: go1.18 # Uses go generics
template: |-
  func Clone[E any, S ~[]E](slice S) S {
    res := make(S, len(slice))
    copy(res, slice)
    return res
  }
```

--------------------------------

### Conventional Commit Examples

Source: https://github.com/datadog/orchestrion/blob/main/CONTRIBUTING.md

Examples of conventional commit messages for bug fixes. Bug fix PR titles should refer to the bug, not the solution.

```git
- :x: `fix: infer -coverpkg argument if absent`
```

```git
- :white_check_mark: `fix: link step fails if -cover is used without -coverpkg`
```

--------------------------------

### Build with Orchestrion (Option 1)

Source: https://github.com/datadog/orchestrion/blob/main/_docs/content/docs/getting-started.md

Use `orchestrion go` commands as a replacement for standard `go` commands to build, run, or test your project with Orchestrion instrumentation.

```bash
$ orchestrion go build .
```

```bash
$ orchestrion go run .
```

```bash
$ orchestrion go test ./...
```

--------------------------------

### Create New Test Directory and Module

Source: https://github.com/datadog/orchestrion/blob/main/test/e2e/README.md

Steps to create a new directory for a test case and initialize a Go module within it. This sets up the basic structure for a new test.

```bash
mkdir test/e2e/my-test
cd test/e2e/my-test
go mod init github.com/DataDog/orchestrion/test/e2e/my-test
```

--------------------------------

### Run New E2E Test

Source: https://github.com/datadog/orchestrion/blob/main/test/e2e/README.md

Execute the newly created E2E test using `go test`. Remember to include the `-tags=e2e` flag.

```bash
go test -tags=e2e -v .
```

--------------------------------

### Run All E2E Tests

Source: https://github.com/datadog/orchestrion/blob/main/test/e2e/README.md

Execute all end-to-end tests using the provided make command. Ensure you are in the project root directory.

```bash
make test-e2e
```

--------------------------------

### Running Orchestrion Integration Tests Locally

Source: https://github.com/datadog/orchestrion/blob/main/CONTRIBUTING.md

Steps to clone the dd-trace-go repository, navigate to the integration tests, and configure Go modules to run the orchestrion integration test suite locally.

```bash
$ git clone github.com:DataDog/dd-trace-go         # Clone the DataDog/dd-trace-go repository
$ cd dd-trace-go/internal/orchestrion/_integration # Move into the integration tests directory
$ go mod edit \
    -replace "github.com/DataDog/orchestrion=>${orchestrion_dir}"
$ go mod tidy                                      # Make sure go.mod & go.sum are up-to-date
$ go run github.com/DataDog/orchestrion \
    go test -shuffle=on ./...
```

--------------------------------

### Enable and Collect Go Profiler Data

Source: https://github.com/datadog/orchestrion/blob/main/_docs/content/contributing/performance.md

Use these command-line arguments with `orchestrion` to enable CPU, heap, or trace profiling. Specify a directory for output and enable one or more profiler types. Enabling profiles may impact build performance.

```console
$ orchestrion --profile-path="$PWD/profiles" --profile=cpu go build .
$ go tool pprof -proto $PWD/profiles/*.pprof > profile.pprof
$ go tool pprof -http=localhost:6060 profile.pprof
```

--------------------------------

### Basic Template with Imports

Source: https://github.com/datadog/orchestrion/blob/main/_docs/content/contributing/aspects/code-templates.md

Demonstrates binding a Go package to an identifier for use within a template. The template uses `fmt.Println` which is mapped to the `fmt` package.

```yaml
template: fmt.Println({{ . }})
imports:
  # The template uses `fmt` so we bind it to the identifier `fmt` below.
  fmt: fmt
```

--------------------------------

### Copying AST Node with '.AST.Copy()'

Source: https://github.com/datadog/orchestrion/blob/main/_docs/content/contributing/aspects/code-templates.md

Illustrates how to copy an AST node using `.AST.Copy()` to avoid issues with nodes appearing multiple times. Copied nodes are treated as synthetic.

```go-template
{{ .AST.Copy }}
```

--------------------------------

### Pin Orchestrion Configuration File

Source: https://github.com/datadog/orchestrion/blob/main/_docs/content/docs/configuration.md

Use the `orchestrion pin` command to create the `orchestrion.tool.go` file if it doesn't exist. By default, this command enables Datadog's tracer integrations.

```bash
orchestrion pin
```

--------------------------------

### Default Orchestrion Configuration

Source: https://github.com/datadog/orchestrion/blob/main/_docs/content/docs/configuration.md

The default `orchestrion.tool.go` file imports all integrations provided by the `github.com/DataDog/dd-trace-go/orchestrion/all/v2` package.

```go
package main

import (
	_ "github.com/DataDog/dd-trace-go/orchestrion/all/v2"
)

```

--------------------------------

### Build with Orchestrion (Option 3)

Source: https://github.com/datadog/orchestrion/blob/main/_docs/content/docs/getting-started.md

Set the `GOFLAGS` environment variable to include the `-toolexec` argument for `orchestrion toolexec`. This enables normal `go` commands to use Orchestrion.

```bash
$ export GOFLAGS="${GOFLAGS} '-toolexec=orchestrion toolexec'"
```

```bash
$ go build .
```

```bash
$ go run .
```

```bash
$ go test ./...
```

--------------------------------

### Build with Orchestrion (Option 2)

Source: https://github.com/datadog/orchestrion/blob/main/_docs/content/docs/getting-started.md

Manually specify the `-toolexec` argument with `orchestrion toolexec` for `go` commands. This allows Orchestrion to intercept build processes.

```bash
$ go build -toolexec 'orchestrion toolexec' .
```

```bash
$ go run -toolexec 'orchestrion toolexec' .
```

```bash
$ go test -toolexec 'orchestrion toolexec' ./...
```

--------------------------------

### Using Version Function in Template

Source: https://github.com/datadog/orchestrion/blob/main/_docs/content/contributing/aspects/code-templates.md

Demonstrates how to use the `Version` function within a Go template to output the Orchestrion version.

```go-template
fmt.Println("Orchestrion version is: {{ Version }}")
```

--------------------------------

### Apache-2.0 License Header

Source: https://github.com/datadog/orchestrion/blob/main/CONTRIBUTING.md

All files in the repository must include this license header. Code copied from other repositories requires the original license header below this one.

```go
// Unless explicitly stated otherwise all files in this repository are licensed
// under the Apache License Version 2.0.
// This product includes software developed at Datadog (https://www.datadoghq.com/).
// Copyright 2023-present Datadog, Inc.
```

--------------------------------

### Go Toolchain Version Check

Source: https://github.com/datadog/orchestrion/blob/main/_docs/content/contributing/introduction.md

Standard output from Go toolchain commands when checking for full version information.

```console
$ go tool compile -V=full
compile version go1.22.5
```

```console
$ go tool asm -V=full
asm version go1.22.5
```

--------------------------------

### Run Specific E2E Test Case

Source: https://github.com/datadog/orchestrion/blob/main/test/e2e/README.md

Navigate to the specific test directory and run tests using `go test`. The `-tags=e2e` flag is mandatory for E2E tests.

```bash
cd test/e2e/pgo
go test -tags=e2e -v .
```

--------------------------------

### Finer Grain Orchestrion Instrumentation

Source: https://github.com/datadog/orchestrion/blob/main/_docs/content/docs/configuration.md

Replace the default all-inclusive import with specific integrations from `github.com/DataDog/dd-trace-go/orchestrion/all/v2` to use a subset of integrations.

```go
package main

import (
	_ "github.com/DataDog/dd-trace-go/contrib/net/http/orchestrion"
	_ "github.com/DataDog/dd-trace-go/contrib/database/sql/orchestrion"
)

```

--------------------------------

### Inspect Instrumented Packages

Source: https://github.com/datadog/orchestrion/blob/main/_docs/content/docs/getting-started.md

Use the `-work` and `-a` flags with your build command, then use `orchestrion diff --package` with the generated `WORK` directory to see which packages are instrumented.

```bash
$ go build -work -a -toolexec 'orchestrion toolexec' .
```

```bash
WORK=/tmp/go-build123456789
```

```bash
$ orchestrion diff --package /tmp/go-build123456789
```

--------------------------------

### Orchestrion -toolexec Integration with Go Build Cache

Source: https://github.com/datadog/orchestrion/blob/main/_docs/content/contributing/introduction.md

Demonstrates how Orchestrion intercepts Go toolchain commands with -V=full to append its own versioning information, including injectables and aspects, for GOCACHE integration.

```shell
$ orchestrion toolexec $(go env GOTOOLDIR)/compile -V=full
compile version go1.22.5:orchestrion@v0.7.2+MqXURZSvaKZl7setr4REn5Jn6AlQBABEe3QuUlyYTzW4yJ2XhUTMdsUnd1xjjnvTSxcV76mP7mquaAQCo7nwow==;injectables=lGUc8QV91HuOK1yWcSxkfmUFLQbKekTyy0eANpJE0rmeGmHR5D61VXn04/XX2kjuPbo8Nrdo+dFBmKPgpKV9jQ==;aspects=sha512:M1yO7gdlnh5Uy2ySDJZp1/QbFL97hY5HGKHYpIq2r561weEn4pAbseW7yBGNuQAP8lTpY4Id8M5jC1ItvVcj2w==
```

--------------------------------

### Moving AST Node with '.'

Source: https://github.com/datadog/orchestrion/blob/main/_docs/content/contributing/aspects/code-templates.md

Shows the basic usage of `{{ . }}` to move the current AST node into the template output. This preserves source position information.

```go-template
{{ . }}
```

--------------------------------

### Checkout Release Branch

Source: https://github.com/datadog/orchestrion/blob/main/RELEASING.md

Fetches the latest changes and checks out a new branch for the release. Replace `vX.Y.Z` with the actual version number.

```console
git fetch
git checkout origin/main -b ${USER}/release/vX.Y.Z
```

--------------------------------

### Default Orchestrion Tracer Configuration

Source: https://github.com/datadog/orchestrion/blob/main/_docs/content/docs/dd-trace-go/_index.md

This Go code configures the default tracer integrations for Orchestrion. It includes essential integrations and allows for automatic discovery of new ones by running `orchestrion pin`.

```go
//go:build tools

//go:generate go run github.com/DataDog/orchestrion pin

package tools

// Imports in this file determine which tracer integrations are enabled in
// orchestrion. New integrations can be automatically discovered by running
// `orchestrion pin` again. You can also manually add new imports here to
// enable additional integrations. When doing so, you can run `orchestrion pin`
// to make sure manually added integrations are valid (i.e, the imported package
// includes a valid `orchestrion.yml` file).
import (
	// Ensures `orchestrion` is present in `go.mod` so that builds are repeatable.
	// Do not remove.
	_ "github.com/DataDog/orchestrion"

	// Provides integrations for essential `orchestrion` features. Most users
	// should not remove this integration.
	_ "github.com/DataDog/dd-trace-go/orchestrion/all/v2" // integration
)
```

--------------------------------

### Specific Orchestrion Tracer Integrations

Source: https://github.com/datadog/orchestrion/blob/main/_docs/content/docs/dd-trace-go/_index.md

This Go code configures specific tracer integrations for Orchestrion, such as the core tracer library and net/http clients and servers. It replaces the default `all/v2` import with targeted packages.

```go
//go:build tools

//go:generate go run github.com/DataDog/orchestrion pin

package tools

// Imports in this file determine which tracer integrations are enabled in
// orchestrion. New integrations can be automatically discovered by running
// `orchestrion pin` again. You can also manually add new imports here to
// enable additional integrations. When doing so, you can run `orchestrion pin`
// to make sure manually added integrations are valid (i.e, the imported package
// includes a valid `orchestrion.yml` file).
import (
	// Ensures `orchestrion` is present in `go.mod` so that builds are repeatable.
	// Do not remove.
	_ "github.com/DataDog/orchestrion"

	// Provides integrations for essential `orchestrion` features. Most users
	// should not remove this integration.
	_ "gopkg.in/DataDog/dd-trace-go.v1/ddtrace/tracer"   // integration
	_ "gopkg.in/DataDog/dd-trace-go.v1/contrib/net/http" // integration
)
```

--------------------------------

### Create Pull Request

Source: https://github.com/datadog/orchestrion/blob/main/RELEASING.md

Opens a new pull request in the web interface for the current branch.

```console
gh pr create --web
```

--------------------------------

### Orchestrion Compilation Sequence Diagram

Source: https://github.com/datadog/orchestrion/blob/main/_docs/content/docs/architecture.md

Visualizes the interaction between the Go toolchain, Orchestrion, the job server, and the Go compiler during package compilation.

```mermaid
sequenceDiagram
  autonumber

  participant Toolchain as go toolchain
  participant Orchestrion as orchestrion toolexec
  participant JobServer as orchestrion job server
  participant Compiler as go tool compile

  loop For each package
    Toolchain ->>+ Orchestrion: compile ${args...}
    note over Toolchain,JobServer: The job server ensures a given package is compiled exactly once
    alt first build of package
      Orchestrion ->>+ JobServer: build.Start
      JobServer ->>- Orchestrion: token
      Orchestrion ->> Orchestrion: instrument .go files
      Orchestrion ->>+ JobServer: packages.Resolve
      note right of JobServer: injected packages
      JobServer ->>+ Toolchain: packages.Load
      Toolchain -->>- JobServer: packages
      JobServer -->>- Orchestrion: archives
      opt When package is "main"
        Orchestrion ->> Orchestrion: write link-deps.go
      end
      Orchestrion ->> Orchestrion: update -importcfg file
      note over Orchestrion,Compiler: Invoke the actual compiler tool
      Orchestrion -->>+ Compiler: ${args...}
      Compiler ->>- Orchestrion: exit code
      Orchestrion ->> Orchestrion: add link.deps to -output file
      Orchestrion ->>+ JobServer: build.Finish
      JobServer -->>- Orchestrion: ack
    else subsequent build of package (idempotent)
      Orchestrion ->>+ JobServer: build.Start
      JobServer ->>- Orchestrion: idempotent
      Orchestrion ->> Orchestrion: Copy build artifacts
    end
    Orchestrion -->>- Toolchain: exit code
  end
```

--------------------------------

### Desired Order: Error Tracking + Span Creation

Source: https://github.com/datadog/orchestrion/blob/main/_docs/content/adr/0002-aspect-application-order.md

Shows the correct execution order where error processing occurs before error capture, ensuring accurate span error reporting.

```go
func getError(ctx context.Context) (__result__0 error) {

  var span tracer.Span
  span, ctx = tracer.StartSpanFromContext(ctx, "getError")
  // Error capture happens LATER because of the defer order
  defer func() {
    span.Finish(tracer.WithError(__result__0))  // Captures processed error
  }()
  // Error processing happens FIRST
  defer func() {
    __result__0 = errortrace.Wrap(__result__0)  // Processes error
  }()
  // Original function body...
}
```

--------------------------------

### Problematic Current Order: Error Tracking + Span Creation

Source: https://github.com/datadog/orchestrion/blob/main/_docs/content/adr/0002-aspect-application-order.md

Illustrates the incorrect execution order where error capture happens before error processing, leading to ineffective span error reporting.

```go
func getError(ctx context.Context) (__result__0 error) {
  var span tracer.Span
  span, ctx = tracer.StartSpanFromContext(ctx, "getError")
  // Error capture happens FIRST because of the defer order
  defer func() {
    span.Finish(tracer.WithError(__result__0))  // Captures unprocessed error
  }()
    // Error processing happens LATER (wrong order), we only have "prepend statements" so we need "defer"
  defer func() {
    __result__0 = errortrace.Wrap(__result__0)  // Processes error after capture
  }()
  // Original function body...
}
```

--------------------------------

### Add Dependencies for New Test

Source: https://github.com/datadog/orchestrion/blob/main/test/e2e/README.md

Modify the go.mod file to include necessary dependencies for the new test. This ensures the test can access the Orchestrion module and its test utilities.

```bash
go mod edit -require=github.com/DataDog/orchestrion/test/e2e@v0.0.0
go mod edit -replace=github.com/DataDog/orchestrion/test/e2e=..
go mod edit -replace=github.com/DataDog/orchestrion=../../..
go mod tidy
```

--------------------------------

### Create Custom Trace Spans with //dd:span

Source: https://github.com/datadog/orchestrion/blob/main/_docs/content/docs/dd-trace-go/custom-trace.md

Annotate functions with `//dd:span` to create trace spans around their execution. Custom tags can be provided as `key:value` pairs.

```go
//dd:span tag-name:foo other-tag:bar
func tracedFunction() {
  // This function will be represented as a span named "tracedFunction"
}
```

--------------------------------

### Send Orchestrion Logs to File

Source: https://github.com/datadog/orchestrion/blob/main/_docs/content/docs/troubleshooting.md

Direct orchestrion's logging output to a file by setting the ORCHESTRION_LOG_FILE environment variable or using the --log-file flag. The tokens $PID and ${PID} are replaced with the process ID. Setting this variable also defaults the log level to WARN.

```shell
export ORCHESTRION_LOG_FILE=/var/log/orchestrion.log
```

```shell
orchestrion --log-file=./orchestrion.log build ./...
```

```shell
export ORCHESTRION_LOG_FILE=/tmp/orchestrion-$PID.log
```

--------------------------------

### Preserve Go Build Work Tree

Source: https://github.com/datadog/orchestrion/blob/main/_docs/content/docs/troubleshooting.md

Use the -work flag with orchestrion go build to preserve the build's work tree for later inspection. The WORK directory path is printed at the beginning of the build.

```console
$ orchestrion go build -work ./...
WORK=/tmp/go-build2455442813
```

--------------------------------

### Go Toolchain Version Output

Source: https://github.com/datadog/orchestrion/blob/main/_docs/content/docs/architecture.md

This console output shows how Orchestrion modifies the Go toolchain's compile version string. It appends Orchestrion's version and a base64-encoded hash, which includes configuration details and information about injected packages.

```console
compile version go1.23.6:orchestrion@v1.1.0-rc.1;<base64-encoded-hash>
```

--------------------------------

### Pin Orchestrion Version

Source: https://github.com/datadog/orchestrion/blob/main/_docs/content/docs/getting-started.md

Register Orchestrion in your project's `go.mod` file to ensure reproducible builds. Remember to commit the updated `go.mod` and `go.sum` files.

```bash
$ orchestrion pin
```

--------------------------------

### Template with Deferred Function Calls

Source: https://github.com/datadog/orchestrion/blob/main/_docs/content/contributing/aspects/code-templates.md

Shows how to use imports for functions that require deferred execution. The `tracer` identifier is bound to the DataDog tracing package.

```yaml
template: |-
  tracer.Start()
  defer tracer.Stop()
imports:
  tracer: gopkg.in/DataDog/dd-trace-go.v1/ddtrace/tracer
```

--------------------------------

### Configure Orchestrion Log Level

Source: https://github.com/datadog/orchestrion/blob/main/_docs/content/docs/troubleshooting.md

Set the ORCHESTRION_LOG_LEVEL environment variable or use the --log-level flag to control the verbosity of orchestrion's logging output. Higher levels like DEBUG or TRACE can impact build performance.

```shell
export ORCHESTRION_LOG_LEVEL=DEBUG
```

```shell
orchestrion --log-level=TRACE build ./...
```

--------------------------------

### Orchestrion Linker Interception Sequence Diagram

Source: https://github.com/datadog/orchestrion/blob/main/_docs/content/docs/architecture.md

This diagram illustrates the sequence of interactions when Orchestrion intercepts the Go linker command. It shows how Orchestrion interacts with the Go toolchain, job server, and the actual linker to update import configurations and perform linking.

```mermaid
sequenceDiagram
  autonumber

  participant Toolchain as go toolchain
  participant Orchestrion as orchestrion toolexec
  participant JobServer as orchestrion job server
  participant Linker as go tool link

  loop For each executable
    Toolchain ->>+ Orchestrion: link ${args...}
    loop For each -importcfg entry
      Orchestrion ->> Orchestrion: read link.deps object
      Orchestrion ->>+ JobServer: packages.Resolve
      note right of JobServer: un-satisfied link-time dependencies
      JobServer ->>+ Toolchain: packages.Load
      Toolchain -->>- JobServer: packages
      JobServer -->>- Orchestrion: archives
    end
    Orchestrion ->> Orchestrion: update -importcfg file
    note over Orchestrion,Linker: Invoke the actual linker tool
    Orchestrion -->>+ Linker: ${args...}
    Linker ->>- Orchestrion: exit code
    Orchestrion -->>- Toolchain: exit code
  end
```

--------------------------------

### Extract Directive Arguments with .DirectiveArgs

Source: https://github.com/datadog/orchestrion/blob/main/_docs/content/contributing/aspects/code-templates.md

Use the `.DirectiveArgs` method to find directives in the AST and extract their key-value arguments. This is useful for processing custom comments like `//dd:span`.

```go-template
{{- $ctx := .Function.ArgumentOfType "context.Context" -}}
{{- $name := .Function.Name -}}
{{$ctx}} = instrument.Report({{$ctx}}, event.EventStart{{with $name}}, "function-name", {{printf "%q" .}}{{end}}
{{- range .DirectiveArgs "dd:span" -}}
  , {{printf "%q" .Key}}, {{printf "%q" .Value}}
{{- end -}})
defer instrument.Report({{$ctx}}, event.EventEnd{{with $name}}, "function-name", {{printf "%q" .}}{{end}}
{{- range .DirectiveArgs "dd:span" -}}
  , {{printf "%q" .Key}}, {{printf "%q" .Value}}
{{- end -}}}
```

--------------------------------

### Linking GitHub Issues in PR Body

Source: https://github.com/datadog/orchestrion/blob/main/CONTRIBUTING.md

Use header-style footers in the PR body to link to relevant GitHub issues. 'Fixes' will close the issue when merged.

```git
- `Fixes: #123` - fixes the bug/issue number `123` reported on this repository
```

```git
- `Depends-On: DataDog/dd-trace-go#456` - depends on issue/PR number `456` in the `DataDog/dd-trace-go` repository
```

--------------------------------

### Commit Version Update

Source: https://github.com/datadog/orchestrion/blob/main/RELEASING.md

Commits the change to the version file after updating the tag constant. Ensure `vX.Y.Z` matches the release version.

```console
git commit -m "release: vX.Y.Z" internal/version/version.go
```

--------------------------------

### Capture Error Information in Spans

Source: https://github.com/datadog/orchestrion/blob/main/_docs/content/docs/dd-trace-go/custom-trace.md

Functions annotated with `//dd:span` that return an error will automatically include non-nil error information in the span.

```go
package demo

import "errors"

//dd:span
func failableFunction() (any, error) {
  // This span will have error information attached automatically.
  return nil, errors.ErrUnsupported
}
```

--------------------------------

### Propagate Trace Context Across Goroutines

Source: https://github.com/datadog/orchestrion/blob/main/_docs/content/docs/dd-trace-go/custom-trace.md

Pass trace context explicitly when launching child goroutines to ensure traces are not split. The `//dd:span` directive instruments the `caller` function, and its context is passed to `callee`.

```go
package demo

//dd:span
func caller(ctx context.Context) {
  wait := make(chan struct{}, 1)
  defer close(wait)

  // Weaving the span context into the child goroutine
  go callee(ctx, wait)
  <-wait
}

//dd:span
func callee(ctx context.Context, done chan<- struct{}) {
  done <- struct{}{}
}
```

--------------------------------

### Prevent Instrumentation with //orchestrion:ignore

Source: https://github.com/datadog/orchestrion/blob/main/_docs/content/docs/dd-trace-go/custom-trace.md

Use the `//orchestrion:ignore` directive to disable instrumentation for specific functions or code blocks. Note that not all integrations support opting out.

```go
package demo

import "net/http"

//orchestrion:ignore I don't want any of this to be instrumented, ever.
func noInstrumentationThere() {
  // Orchestrion will never add or modify any code in this function
  // ... etc ...
}

func definitelyInstrumented() {
  // Orchestrion may add or modify code in this function
  // ... etc ...

  //orchestrion:ignore This particular database connection will NOT be instrumented
  db, err := db.Open("driver-name", "database=example")

  // Orchestrion may add or modify code further down in this function
  // ... etc ...
}
```

--------------------------------

### Specify Operation Name with //dd:span

Source: https://github.com/datadog/orchestrion/blob/main/_docs/content/docs/dd-trace-go/custom-trace.md

Control the span name by providing `span.name:operationName` as a directive argument. If not provided, the function name or the first tag value is used.

```go
//dd:span span.name:operationName
func tracedFunction() {
  // This function will be represented as a span named "operationName"
}
```

```go
//dd:span tag-name:for other-tag:bar
func tracedFunction() {
  // This function will be represented as a span named "tracedFunction"
}
```

```go
//dd:span tag-name:spanName other-tag:bar

tracedFunction := func() {
  // This function will be represented as a span named "spanName"
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.