Información general

Orchestrion añade automáticamente Instrumentación a las aplicaciones Go durante la compilación, eliminando la necesidad de realizar cambios en el código. Proporciona una amplia cobertura de rastreo y habilita funciones de seguridad exclusivas:

• Amplia cobertura de rastreo:
  • Instrumenta tu código y todas las dependencias, incluida la biblioteca estándar de Go
  • Instrumenta el código durante la compilación, lo que evita lagunas en la cobertura de rastreo debidas a errores manuales pasados por alto en la instrumentación manual.
• Función Exploit Prevention (Prevención de exploits) exclusiva de Application Security Management. La Prevención de exploits es una implementación de Runtime Application Self-Protection (RASP) e incluye métodos RASP como la inclusión de archivos locales (LFI).

Requisitos

• Admite las dos últimas versiones de Go (que coinciden con la versión oficial de la política de Go]8).
• Las aplicaciones deben gestionarse mediante módulos de Go. Se admite la venta de módulos.

Instalar Orchestrion

Para instalar y configurar Orchestrion:

1. Instalar Orchestrion:

   go install github.com/DataDog/orchestrion@latest
   

   Nota: Asegúrate de que $(go env GOBIN) o $(go env GOPATH)/bin está en tu ruta $PATH.

2. Registra Orchestrion en el go.mod de tu proyecto:

   orchestrion pin
   

   Consulta la salida de orchestrion pin -help para obtener más información sobre las opciones de personalización disponibles.

3. Confirma los cambios en tu sistema de control de versiones (a menos que estés integrando orchestrion directamente en tu proceso de CI/CD):

   git add go.mod go.sum orchestrion.tool.go
   git commit -m "chore: enable orchestrion"
   

   Ahora puedes gestionar tu dependencia de orchestrion como cualquier otra dependencia utilizando el archivo go.mod.

Utilización

Utiliza uno de estos métodos para activar Orchestrion en tu proceso de compilación:

Añade orchestrion a tus comandos habituales de go:

orchestrion go build .
orchestrion go run .
orchestrion go test ./...

Añade el argumento -toolexec="orchestrion toolexec" a tus comandos go:

go build -toolexec="orchestrion toolexec" .
go run -toolexec="orchestrion toolexec" .
go test -toolexec="orchestrion toolexec" ./...

Modifica la variable de entorno $GOFLAGS para inyectar Orchestrion y utiliza normalmente los comandos go:

# Make sure to include the quotes as shown below, as these are required for
# the Go toolchain to parse GOFLAGS properly!
export GOFLAGS="${GOFLAGS} '-toolexec=orchestrion toolexec'"
go build .
go run .
go test ./...

Personalización de trazas

Configuración del etiquetado unificado de servicios

Las aplicaciones instrumentadas por orchestrion admiten el etiquetado unificado de servicios (UST). Puedes configurar etiquetas (tags) del UST para tus trazas (traces) al configurar la variable de entorno correspondiente en el entorno de tiempo de ejecución de tu aplicación:

Para más información, consulta la documentación del etiquetado unificado de servicios.

Configuración del rastreador

Consulta Configuración de biblioteca para obtener instrucciones sobre la configuración.

Crear tramos de trazas personalizadas

Se pueden crear automáticamente tramos de trazas personalizadas para cualquier función anotada con el comentario de directiva //dd:span:

//dd:span custom_tag:tag_value
func CriticalPathFunction() {
  // ... detalles de implementación ...
}

Esto también funciona con las expresiones literales de función:

//dd:span custom_tag:tag_value
handler := func(w http.ResponseWriter, r *http.Request) {
  // ... detalles de implementación ...
}

Nombre de la operación

El nombre de la operación (span.name) se determina automáticamente utilizando la siguiente precedencia:

1. Una etiqueta span.name:customOperationName explícita especificada como argumento directivo
2. El nombre declarado de la función (esto no se aplica a las expresiones literales de función, que son anónimas)
3. El valor de la primer etiqueta proporcionada a la lista de argumentos directivos

//dd:span tag-name:spanName other-tag:bar span.name:operationName
func tracedFunction() {
  // Esta función se representará como un tramo denominado "operationName"
}

//dd:span tag-name:spanName other-tag:bar
func otherTracedFunction() {
  // Esta función se representará como un tramo denominado "otherTracedFunction"
}

//dd:span tag-name:spanName other-tag:bar
tracedFunction := func() {
  // Esta función se representará como un tramo denominado "spanName"
}

Resultados de errores

Si la función anotada devuelve un resultado error, cualquier error devuelto por la función se adjuntará automáticamente al tramo de traza correspondiente:

//dd:span
func failableFunction() (any, error) {
  // Este tramo tendrá información del error adjunta automáticamente.
  return nil, errors.ErrUnsupported
}

Evitar la instrumentación de algunos códigos

Puedes utilizar la directiva //orchestrion:ignore para evitar que orchestrion realice cualquier modificación en el código anotado.

Esto se puede utilizar para evitar que se aplique la instrumentación del lado de quien llama a localizaciones específicas:

import "database/sql"

// La instrumentación del lado de quien llama normalmente ocurre dentro de esta función...
func normal() {
  // La siguiente asignación NO será modificada para añadir ninguna instrumentación del lado de quien llama 
  // ya que está excluida por la directiva orchestrion:ignore:
  //orchestrion:ignore
  db, err := sql.Open("driver-name", "database=example")
  // ...
}

// La instrumentación del lado de quien llama NO ocurrirá en la siguiente función
// ya que está anotada con orchestrion:ignore.
//orchestrion:ignore
func excluded() {
  // La siguiente asignación NO se modificará para añadir ninguna instrumentación
  // del lado de quien llama, ya que el contexto circundante está excluido por una directiva
  // orchestrion:ignore:
  db, err := sql.Open("driver-name", "database=example")
  // ...
}

Parte de la instrumentación realizada por orchestrion se lleva a cabo del lado del receptor de la llamada (o del lado de biblioteca), lo que significa que la integración se añade directamente dentro de la propia dependencia. En estos casos, no es posible excluir localmente este tipo de integraciones.

Utilizar la biblioteca de rastreo

Puedes utilizar la biblioteca de rastreo en tu aplicación creada con Orchestrion. Esto es útil para instrumentar marcos aún no compatibles por Orchestrion. Sin embargo, ten en cuenta que esto puede resultar en tramos de traza duplicados en el futuro a medida que se amplíe la compatibilidad de Orchestrion. Revisa las notas de la versión cuando actualices tu dependencia de orchestrion para mantenerte informado sobre las nuevas características y ajusta tu instrumentación manual según sea necesario.

Utilizar el perfilador continuo

Tu aplicación creada con Orchestrion incluye la instrumentación del perfilador continuo. Para activar el perfilador, establece la variable de entorno DD_PROFILING_ENABLED=true en el tiempo de ejecución.

Solucionar problemas

Para solucionar los problemas de compilación que gestiona orchestrion, consulta solucionar problemas de instrumentación del tiempo de compilación de Go.

Añadir la biblioteca del rastreador a tu aplicación

En primer lugar, importa e inicia el rastreador en tu código siguiendo la documentación de Configuración de la biblioteca. Consulta la documentación de la API (o la documentación de la API v2) para obtener instrucciones y detalles de configuración sobre el uso de la API.

Integraciones activas de Go para crear tramos

Activa las integraciones de Go para generar tramos. Datadog tiene una serie de paquetes conectables que proporcionan soporte “predefinido” para instrumentar una serie de bibliotecas y marcos. En la página Requisitos de compatibilidad se puede encontrar una lista de estos paquetes. Importa estos paquetes a tu aplicación y sigue las instrucciones de configuración que aparecen junto a cada integración.