Genera seguimientos y métricas con Python

En este documento, se describe cómo modificar una app de Python para recopilar datos de seguimiento y métricas con el framework de código abierto de OpenTelemetry y cómo escribir registros JSON estructurados en salida estándar. En este documento, también se proporciona información sobre una app de Python de muestra que puedes instalar y ejecutar. La app usa el framework web Flask y está configurada para generar métricas, seguimientos y registros.

Información sobre la instrumentación manual y automática

Para este lenguaje, OpenTelemetry define la instrumentación automática como la práctica de recopilar telemetría de bibliotecas y frameworks sin realizar cambios en el código. Sin embargo, tienes módulos de instalación y estableces variables de entorno.

En este documento, no se describe la instrumentación automática. Para obtener más información sobre ese tema, consulta Instrumentación automática para Python.

Si deseas obtener información general, consulta Instrumentación de OpenTelemetry para Python.

Antes de comenzar

Habilita las API de Cloud Logging, Cloud Monitoring, and Cloud Trace.

Habilita las API

Instrumenta tu app para recopilar seguimientos, métricas y registros

Si deseas instrumentar tu app para recopilar datos de seguimiento y métricas, y escribir JSON estructurado en la salida estándar, realiza los pasos que se describen en las siguientes secciones de este documento:

Configura OpenTelemetry
Configura el registro estructurado

Configura OpenTelemetry

Esta app de ejemplo está configurada para usar el SDK de Python de OpenTelemetry a fin de exportar seguimientos y métricas mediante el protocolo OTLP. De forma predeterminada, el SDK de OpenTelemetry para Python usa el formato de contexto de seguimiento W3C a fin de propagar el contexto de seguimiento, lo que garantiza que los intervalos tengan la relación correcta de elementos superiores-secundarios dentro de un seguimiento.

En la siguiente muestra de código, se ilustra un módulo de Python para configurar OpenTelemetry. Para ver la muestra completa, haz clic en Más y, luego, selecciona Ver en GitHub.

resource = Resource.create(attributes={
    # Use the PID as the service.instance.id to avoid duplicate timeseries
    # from different Gunicorn worker processes.
    SERVICE_INSTANCE_ID: f"worker-{os.getpid()}",
})

traceProvider = TracerProvider(resource=resource)
processor = BatchSpanProcessor(OTLPSpanExporter())
traceProvider.add_span_processor(processor)
trace.set_tracer_provider(traceProvider)

reader = PeriodicExportingMetricReader(
    OTLPMetricExporter()
)
meterProvider = MeterProvider(metric_readers=[reader], resource=resource)
metrics.set_meter_provider(meterProvider)

La app de Flask se basa en Gunicorn para entregar solicitudes HTTP, de acuerdo con las recomendaciones de la guía Implementa en producción de Flask. Gunicorn inicia varias copias de tu app que se ejecutan en procesos de trabajadores independientes para aumentar la capacidad de procesamiento. A fin de garantizar que las métricas de los procesos de los trabajadores no entren en conflicto, recomendamos que cada proceso de trabajador establezca un valor único para el atributo de recurso service.instance.id. Una forma de hacerlo es incluir el ID del proceso en la service.instance.id. Para obtener más información, consulta Colisiones de series temporales.

Para obtener más información y opciones de configuración, consulta Instrumentación de Python de OpenTelemetry.

Configura el registro estructurado

A fin de escribir registros estructurados que estén vinculados a seguimientos, configura la app para que genere registros con formato JSON en salida estándar con claves que contengan información de seguimiento. En la siguiente muestra de código, se ilustra cómo configurar la biblioteca logging estándar para generar registros estructurados JSON mediante la biblioteca python-json-logger, y cómo para usar el paquete opentelemetry-instrumentation-logging para incluir información de seguimiento.

LoggingInstrumentor().instrument()

logHandler = logging.StreamHandler()
formatter = jsonlogger.JsonFormatter(
    "%(asctime)s %(levelname)s %(message)s %(otelTraceID)s %(otelSpanID)s %(otelTraceSampled)s",
    rename_fields={
        "levelname": "severity",
        "asctime": "timestamp",
        "otelTraceID": "logging.googleapis.com/trace",
        "otelSpanID": "logging.googleapis.com/spanId",
        "otelTraceSampled": "logging.googleapis.com/trace_sampled",
        },
    datefmt="%Y-%m-%dT%H:%M:%SZ",
)
logHandler.setFormatter(formatter)
logging.basicConfig(
    level=logging.INFO,
    handlers=[logHandler],
)

La configuración anterior extrae información sobre el intervalo activo del mensaje de registro y, luego, agrega esa información como atributos al registro estructurado JSON. Estos atributos se pueden usar para correlacionar un registro con un seguimiento:

logging.googleapis.com/trace: el nombre del recurso del seguimiento asociado a la entrada de registro.
logging.googleapis.com/spanId: el ID de intervalo con el seguimiento asociado a la entrada de registro.
logging.googleapis.com/trace_sampled: el valor de este campo debe ser true o false.

Para obtener más información sobre estos campos, consulta la estructura LogEntry.

Ejecuta una app de ejemplo configurada para recopilar telemetría

En la aplicación de ejemplo, se usan formatos independientes del proveedor, incluido JSON para los registros y OTLP para las métricas y los seguimientos. La telemetría de la app se enruta a Google Cloud mediante el Collector de OpenTelemetry configurado con los exportadores de Google. Usa Flask para entregar solicitudes HTTP y la biblioteca requests para realizar solicitudes HTTP. Para generar métricas y seguimientos para el cliente y el servidor HTTP, la app de ejemplo instala las bibliotecas de instrumentación opentelemetry-instrumentation-flask y opentelemetry-instrumentation-requests:

logger = logging.getLogger(__name__)

app = Flask(__name__)
FlaskInstrumentor().instrument_app(app)
RequestsInstrumentor().instrument()

La app tiene dos extremos:

La función multi controla el extremo /multi. El generador de cargas de la app envía solicitudes al extremo /multi. Cuando este extremo recibe una solicitud, envía entre tres y siete solicitudes al extremo /single en el servidor local.

@app.route('/multi')
def multi():
    """Handle an http request by making 3-7 http requests to the /single endpoint."""
    subRequests = randint(3, 7)
    logger.info("handle /multi request", extra={'subRequests': subRequests})
    for _ in range(subRequests):
        requests.get(url_for('single', _external=True))
    return 'ok'

La función single controla el extremo /single. Cuando este extremo recibe una solicitud, se suspende durante un retraso breve y, luego, responde con una cadena.

@app.route('/single')
def single():
    """Handle an http request by sleeping for 100-200 ms, and write the number of seconds slept as the response."""
    duration = uniform(0.1, 0.2)
    time.sleep(duration)
    return f'slept {duration} seconds'

Descarga e implementa la app

Para ejecutar la muestra, haz lo siguiente:

En la consola de Google Cloud, activa Cloud Shell.

Activar Cloud Shell

En la parte inferior de la consola de Google Cloud, se inicia una sesión de Cloud Shell en la que se muestra una ventana de línea de comandos. Cloud Shell es un entorno de shell con Google Cloud CLI ya instalada y con valores ya establecidos para el proyecto actual. La sesión puede tardar unos segundos en inicializarse.

Clona el repositorio:

git clone https://github.com/GoogleCloudPlatform/opentelemetry-operations-python

Ve al directorio de muestra:

cd opentelemetry-operations-python/samples/instrumentation-quickstart

Compila y ejecuta la muestra:

docker compose up --abort-on-container-exit

Si no ejecutas en Cloud Shell, ejecuta la aplicación con la variable de entorno GOOGLE_APPLICATION_CREDENTIALS que apunta a un archivo de credenciales. Las credenciales predeterminadas de la aplicación proporcionan un archivo de credenciales en $HOME/.config/gcloud/application_default_credentials.json.

# Set environment variables
export GOOGLE_CLOUD_PROJECT="PROJECT_ID"
export GOOGLE_APPLICATION_CREDENTIALS="$HOME/.config/gcloud/application_default_credentials.json"
export USERID="$(id -u)"

# Run
docker compose -f docker-compose.yaml -f docker-compose.creds.yaml up --abort-on-container-exit

Consulta tus métricas

La instrumentación de OpenTelemetry en la app de ejemplo genera métricas de Prometheus que puedes ver mediante el Explorador de métricas:

Prometheus/http_server_duration_milliseconds/histogram registra la duración de las solicitudes del servidor y almacena los resultados en un histograma.
Prometheus/http_client_duration_milliseconds/histogram registra la duración de las solicitudes del cliente y almacena los resultados en un histograma.

Para ver las métricas que genera la app de muestra, haz lo siguiente:

En la consola de Google Cloud, ve a la página Explorador de métricas:
Dirígete al Explorador de métricas

Si usas la barra de búsqueda para encontrar esta página, selecciona el resultado cuyo subtítulo es Monitoring.
En el elemento Métrica, expande el menú Seleccionar una métrica, ingresa http_server en la barra de filtros y, luego, usa los submenús para seleccionar un métrica y tipo de recurso específicos:
1. En el menú Recursos activos, elige Destino de Prometheus.
2. En el menú Categorías de métricas activas, elige Http.
3. En el menú Métricas activas, selecciona una métrica.
4. Haz clic en Aplicar.
Configura cómo se ven los datos.
Cuando las mediciones de una métrica son acumulativas, el Explorador de métricas normaliza automáticamente los datos medidos por el período de alineación, lo que hace que el gráfico muestre una frecuencia. Para obtener más información, consulta Categorías, tipos y conversiones.

Cuando se miden valores de números enteros o dobles, como con las dos métricas counter, el Explorador de métricas suma automáticamente todas las series temporales. Para ver los datos de las rutas HTTP /multi y /single, establece el primer menú de la entrada Agregación como Ninguna.

Para obtener más información sobre la configuración de un gráfico, consulta elige métricas cuando uses el Explorador de métricas.

Ve tus seguimientos

Para ver tus datos de seguimiento, haz lo siguiente:

En la consola de Google Cloud, ve a la página Explorador de seguimiento:
Ve al Explorador de seguimiento

También puedes usar la barra de búsqueda para encontrar esta página.
En el gráfico de dispersión, selecciona un seguimiento con el URI de /multi.
En el diagrama de Gantt del panel Detalles de seguimiento, selecciona el intervalo etiquetado como /multi.

Se abre un panel que muestra información sobre la solicitud HTTP. Estos detalles incluyen el método, el código de estado, la cantidad de bytes y el usuario-agente del emisor.
Para ver los registros asociados con este seguimiento, selecciona la pestaña Registros y eventos.

La pestaña muestra registros individuales. Para ver los detalles de la entrada de registro, expande la entrada de registro. También puedes hacer clic en Ver registros y ver el registro con el Explorador de registros.

Si deseas obtener más información para usar el explorador de Cloud Trace, consulta Busca y explora seguimientos.

Mira los registros

En el Explorador de registros, puedes inspeccionar tus registros y, también, puedes ver los seguimientos asociados, cuando existen.

En la consola de Google Cloud, ve a la página Explorador de registros:
Ir al Explorador de registros

Si usas la barra de búsqueda para encontrar esta página, selecciona el resultado cuyo subtítulo es Logging.
Ubica un registro con la descripción de handle /multi request.

Para ver los detalles del registro, expande la entrada de registro.
Haz clic en Seguimientos en una entrada de registro con el mensaje "Controla solicitudes múltiples" y, luego, selecciona Ver detalles de seguimiento.

Se abrirá el panel Detalles de seguimiento y se mostrará el seguimiento seleccionado.

Para obtener más información sobre el uso del Explorador de registros, consulta Visualiza registros con el Explorador de registros.