Inspección de datos de telemetría con la consola
Aunque la consola no es una manera recomendada de inspeccionar los datos de telemetría, es una manera sencilla y rápida de empezar. En este artículo se muestra cómo generar datos de telemetría en la consola para su inspección con una configuración mínima del kernel.
Exportador
Los exportadores son responsables de enviar datos de telemetría a un destino. Obtenga más información sobre los exportadores aquí. En este ejemplo, se usa el exportador de la consola para generar datos de telemetría en la consola.
Requisitos previos
- Una implementación de finalización de chat de Azure OpenAI.
- El SDK de .Net más reciente para el sistema operativo.
- Una implementación de finalización de chat de Azure OpenAI.
- Python 3.10, 3.11 o 3.12 instalado en el equipo.
Nota:
La observabilidad semántica del kernel aún no está disponible para Java.
Configurar
Creación de una nueva aplicación de consola
En un terminal, ejecute el siguiente comando para crear una nueva aplicación de consola en C#:
dotnet new console -n TelemetryConsoleQuickstart
Vaya al directorio del proyecto recién creado una vez completado el comando.
Instalación de los paquetes requeridos
Kernel semántico
dotnet add package Microsoft.SemanticKernelExportador de consola de OpenTelemetry
dotnet add package OpenTelemetry.Exporter.Console
Creación de una aplicación sencilla con kernel semántico
En el directorio del proyecto, abra el Program.cs archivo con su editor favorito. Vamos a crear una aplicación sencilla que use kernel semántico para enviar un mensaje a un modelo de finalización de chat. Reemplace el contenido existente por el código siguiente y rellene los valores necesarios para deploymentName, endpointy apiKey:
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Logging;
using Microsoft.SemanticKernel;
using OpenTelemetry;
using OpenTelemetry.Logs;
using OpenTelemetry.Metrics;
using OpenTelemetry.Resources;
using OpenTelemetry.Trace;
namespace TelemetryConsoleQuickstart
{
class Program
{
static async Task Main(string[] args)
{
// Telemetry setup code goes here
IKernelBuilder builder = Kernel.CreateBuilder();
// builder.Services.AddSingleton(loggerFactory);
builder.AddAzureOpenAIChatCompletion(
deploymentName: "your-deployment-name",
endpoint: "your-azure-openai-endpoint",
apiKey: "your-azure-openai-api-key"
);
Kernel kernel = builder.Build();
var answer = await kernel.InvokePromptAsync(
"Why is the sky blue in one sentence?"
);
Console.WriteLine(answer);
}
}
}
Adición de telemetría
Si ejecuta la aplicación de consola ahora, debería esperar ver una frase que explique por qué el cielo es azul. Para observar el kernel mediante telemetría, reemplace el // Telemetry setup code goes here comentario por el código siguiente:
var resourceBuilder = ResourceBuilder
.CreateDefault()
.AddService("TelemetryConsoleQuickstart");
// Enable model diagnostics with sensitive data.
AppContext.SetSwitch("Microsoft.SemanticKernel.Experimental.GenAI.EnableOTelDiagnosticsSensitive", true);
using var traceProvider = Sdk.CreateTracerProviderBuilder()
.SetResourceBuilder(resourceBuilder)
.AddSource("Microsoft.SemanticKernel*")
.AddConsoleExporter()
.Build();
using var meterProvider = Sdk.CreateMeterProviderBuilder()
.SetResourceBuilder(resourceBuilder)
.AddMeter("Microsoft.SemanticKernel*")
.AddConsoleExporter()
.Build();
using var loggerFactory = LoggerFactory.Create(builder =>
{
// Add OpenTelemetry as a logging provider
builder.AddOpenTelemetry(options =>
{
options.SetResourceBuilder(resourceBuilder);
options.AddConsoleExporter();
// Format log messages. This is default to false.
options.IncludeFormattedMessage = true;
options.IncludeScopes = true;
});
builder.SetMinimumLevel(LogLevel.Information);
});
Por último, quite la marca de comentario de la línea // builder.Services.AddSingleton(loggerFactory); para agregar el generador del registrador al generador.
En el fragmento de código anterior, primero se crea un generador de recursos para compilar instancias de recursos. Un recurso representa la entidad que genera datos de telemetría. Puede obtener más información sobre los recursos aquí. El generador de recursos para los proveedores es opcional. Si no se proporciona, se usa el recurso predeterminado con atributos predeterminados.
A continuación, activamos los diagnósticos con datos confidenciales. Se trata de una característica experimental que permite habilitar diagnósticos para los servicios de IA en el kernel semántico. Con esto activado, verá datos de telemetría adicionales, como las solicitudes enviadas a y las respuestas recibidas de los modelos de IA, que se consideran datos confidenciales. Si no desea incluir datos confidenciales en la telemetría, puede usar otro modificador Microsoft.SemanticKernel.Experimental.GenAI.EnableOTelDiagnostics para habilitar diagnósticos con datos no confidenciales, como el nombre del modelo, el nombre de la operación y el uso de tokens, etc.
A continuación, creamos un generador de proveedores de seguimiento y un generador de proveedores de medidores. Un proveedor es responsable de procesar los datos de telemetría y canalización a los exportadores. Nos suscribimos al Microsoft.SemanticKernel* origen para recibir datos de telemetría de los espacios de nombres semánticos del kernel. Agregamos un exportador de consola al proveedor de seguimiento y al proveedor de medidores. El exportador de la consola envía datos de telemetría a la consola.
Por último, creamos un generador de registradores y agregamos OpenTelemetry como proveedor de registro que envía datos de registro a la consola. Establecemos el nivel Information de registro mínimo en e incluyemos mensajes y ámbitos con formato en la salida del registro. A continuación, se agrega el generador del registrador al generador.
Importante
Un proveedor debe ser un singleton y debe estar activo durante toda la duración de la aplicación. El proveedor debe eliminarse de cuando se cierra la aplicación.
Creación de un nuevo entorno virtual de Python
python -m venv telemetry-console-quickstart
Active el entorno virtual.
telemetry-console-quickstart\Scripts\activate
Instalación de los paquetes requeridos
pip install semantic-kernel
Creación de un script de Python sencillo con kernel semántico
Cree un nuevo script de Python y ábralo con su editor favorito.
New-Item -Path telemetry_console_quickstart.py -ItemType file
Vamos a crear un script de Python sencillo que use kernel semántico para enviar un mensaje a un modelo de finalización de chat. Reemplace el contenido existente por el código siguiente y rellene los valores necesarios para deployment_name, endpointy api_key:
import asyncio
import logging
from opentelemetry._logs import set_logger_provider
from opentelemetry.metrics import set_meter_provider
from opentelemetry.sdk._logs import LoggerProvider, LoggingHandler
from opentelemetry.sdk._logs.export import BatchLogRecordProcessor, ConsoleLogExporter
from opentelemetry.sdk.metrics import MeterProvider
from opentelemetry.sdk.metrics.export import ConsoleMetricExporter, PeriodicExportingMetricReader
from opentelemetry.sdk.metrics.view import DropAggregation, View
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor, ConsoleSpanExporter
from opentelemetry.semconv.resource import ResourceAttributes
from opentelemetry.trace import set_tracer_provider
from semantic_kernel import Kernel
from semantic_kernel.connectors.ai.open_ai import AzureChatCompletion
# Telemetry setup code goes here
async def main():
# Create a kernel and add a service
kernel = Kernel()
kernel.add_service(AzureChatCompletion(
api_key="your-azure-openai-api-key",
endpoint="your-azure-openai-endpoint",
deployment_name="your-deployment-name"
))
answer = await kernel.invoke_prompt("Why is the sky blue in one sentence?")
print(answer)
if __name__ == "__main__":
asyncio.run(main())
Adición de telemetría
Variables de entorno
De forma predeterminada, el kernel no emite intervalos para los conectores de IA, ya que estos intervalos llevan gen_ai atributos que se consideran experimentales. Para habilitar la característica, establezca la variable SEMANTICKERNEL_EXPERIMENTAL_GENAI_ENABLE_OTEL_DIAGNOSTICS de entorno o SEMANTICKERNEL_EXPERIMENTAL_GENAI_ENABLE_OTEL_DIAGNOSTICS_SENSITIVE en true.
Importante
Las solicitudes y finalizaciones se consideran datos confidenciales. El kernel semántico no emitirá estos datos desde los conectores de IA a menos que la SEMANTICKERNEL_EXPERIMENTAL_GENAI_ENABLE_OTEL_DIAGNOSTICS_SENSITIVE variable de entorno esté establecida trueen . Establecer SEMANTICKERNEL_EXPERIMENTAL_GENAI_ENABLE_OTEL_DIAGNOSTICS en true solo emitirá datos no confidenciales, como el nombre del modelo, el nombre de la operación y el uso del token.
Cree un nuevo archivo denominado .env en el mismo directorio que el script y agregue el siguiente contenido:
SEMANTICKERNEL_EXPERIMENTAL_GENAI_ENABLE_OTEL_DIAGNOSTICS_SENSITIVE=true
Código
Si ejecuta el script ahora, debería esperar ver una frase que explique por qué el cielo es azul. Para observar el kernel mediante telemetría, reemplace el # Telemetry setup code goes here comentario por el código siguiente:
# Create a resource to represent the service/sample
resource = Resource.create({ResourceAttributes.SERVICE_NAME: "telemetry-console-quickstart"})
def set_up_logging():
exporter = ConsoleLogExporter()
# Create and set a global logger provider for the application.
logger_provider = LoggerProvider(resource=resource)
# Log processors are initialized with an exporter which is responsible
# for sending the telemetry data to a particular backend.
logger_provider.add_log_record_processor(BatchLogRecordProcessor(exporter))
# Sets the global default logger provider
set_logger_provider(logger_provider)
# Create a logging handler to write logging records, in OTLP format, to the exporter.
handler = LoggingHandler()
# Add filters to the handler to only process records from semantic_kernel.
handler.addFilter(logging.Filter("semantic_kernel"))
# Attach the handler to the root logger. `getLogger()` with no arguments returns the root logger.
# Events from all child loggers will be processed by this handler.
logger = logging.getLogger()
logger.addHandler(handler)
logger.setLevel(logging.INFO)
def set_up_tracing():
exporter = ConsoleSpanExporter()
# Initialize a trace provider for the application. This is a factory for creating tracers.
tracer_provider = TracerProvider(resource=resource)
# Span processors are initialized with an exporter which is responsible
# for sending the telemetry data to a particular backend.
tracer_provider.add_span_processor(BatchSpanProcessor(exporter))
# Sets the global default tracer provider
set_tracer_provider(tracer_provider)
def set_up_metrics():
exporter = ConsoleMetricExporter()
# Initialize a metric provider for the application. This is a factory for creating meters.
meter_provider = MeterProvider(
metric_readers=[PeriodicExportingMetricReader(exporter, export_interval_millis=5000)],
resource=resource,
views=[
# Dropping all instrument names except for those starting with "semantic_kernel"
View(instrument_name="*", aggregation=DropAggregation()),
View(instrument_name="semantic_kernel*"),
],
)
# Sets the global default meter provider
set_meter_provider(meter_provider)
# This must be done before any other telemetry calls
set_up_logging()
set_up_tracing()
set_up_metrics()
En el fragmento de código anterior, primero creamos un recurso para representar el servicio. Un recurso representa la entidad que genera datos de telemetría. Puede obtener más información sobre los recursos aquí. A continuación, creamos tres funciones para configurar el registro, el seguimiento y las métricas. Cada función crea un proveedor para los datos de telemetría respectivos y agrega un exportador de consola al proveedor.
Por último, llamamos a las tres funciones para configurar el registro, el seguimiento y las métricas. Esto debe realizarse antes de cualquier otra llamada de telemetría.
Nota:
La observabilidad semántica del kernel aún no está disponible para Java.
Ejecutar
Ejecute la aplicación de consola con el siguiente comando:
dotnet run
Ejecute el script de Python con el siguiente comando:
python telemetry_console_quickstart.py
Nota:
La observabilidad semántica del kernel aún no está disponible para Java.
Inspección de los datos de telemetría
Entradas de registros
Debería ver varios registros de registro en la salida de la consola. Tienen un aspecto similar al siguiente:
LogRecord.Timestamp: 2024-09-12T21:48:35.2295938Z
LogRecord.TraceId: 159d3f07664838f6abdad7af6a892cfa
LogRecord.SpanId: ac79a006da8a6215
LogRecord.TraceFlags: Recorded
LogRecord.CategoryName: Microsoft.SemanticKernel.KernelFunction
LogRecord.Severity: Info
LogRecord.SeverityText: Information
LogRecord.FormattedMessage: Function InvokePromptAsync_290eb9bece084b00aea46b569174feae invoking.
LogRecord.Body: Function {FunctionName} invoking.
LogRecord.Attributes (Key:Value):
FunctionName: InvokePromptAsync_290eb9bece084b00aea46b569174feae
OriginalFormat (a.k.a Body): Function {FunctionName} invoking.
Resource associated with LogRecord:
service.name: TelemetryConsoleQuickstart
service.instance.id: a637dfc9-0e83-4435-9534-fb89902e64f8
telemetry.sdk.name: opentelemetry
telemetry.sdk.language: dotnet
telemetry.sdk.version: 1.9.0
Hay dos partes en cada registro de registro:
- El registro propio: contiene la marca de tiempo y el espacio de nombres en el que se generó el registro, la gravedad y el cuerpo del registro, y los atributos asociados al registro de registro.
- El recurso asociado al registro de registro: contiene información sobre el servicio, la instancia y el SDK usados para generar el registro de registro.
Actividades
Nota:
Las actividades de .Net son similares a los intervalos de OpenTelemetry. Se usan para representar una unidad de trabajo en la aplicación.
Debería ver varias actividades en la salida de la consola. Tienen un aspecto similar al siguiente:
Activity.TraceId: 159d3f07664838f6abdad7af6a892cfa
Activity.SpanId: 8c7c79bc1036eab3
Activity.TraceFlags: Recorded
Activity.ParentSpanId: ac79a006da8a6215
Activity.ActivitySourceName: Microsoft.SemanticKernel.Diagnostics
Activity.DisplayName: chat.completions gpt-4o
Activity.Kind: Client
Activity.StartTime: 2024-09-12T21:48:35.5717463Z
Activity.Duration: 00:00:02.3992014
Activity.Tags:
gen_ai.operation.name: chat.completions
gen_ai.system: openai
gen_ai.request.model: gpt-4o
gen_ai.response.prompt_tokens: 16
gen_ai.response.completion_tokens: 29
gen_ai.response.finish_reason: Stop
gen_ai.response.id: chatcmpl-A6lxz14rKuQpQibmiCpzmye6z9rxC
Activity.Events:
gen_ai.content.prompt [9/12/2024 9:48:35 PM +00:00]
gen_ai.prompt: [{"role": "user", "content": "Why is the sky blue in one sentence?"}]
gen_ai.content.completion [9/12/2024 9:48:37 PM +00:00]
gen_ai.completion: [{"role": "Assistant", "content": "The sky appears blue because shorter blue wavelengths of sunlight are scattered in all directions by the gases and particles in the Earth\u0027s atmosphere more than other colors."}]
Resource associated with Activity:
service.name: TelemetryConsoleQuickstart
service.instance.id: a637dfc9-0e83-4435-9534-fb89902e64f8
telemetry.sdk.name: opentelemetry
telemetry.sdk.language: dotnet
telemetry.sdk.version: 1.9.0
Hay dos partes en cada actividad:
- La propia actividad: contiene el identificador de intervalo y el identificador de intervalo primario que las herramientas de APM usan para compilar los seguimientos, la duración de la actividad y las etiquetas y eventos asociados a la actividad.
- El recurso asociado a la actividad: contiene información sobre el servicio, la instancia y el SDK usados para generar la actividad.
Importante
Los atributos a los que se debe prestar atención adicional son los que comienzan por gen_ai. Estos son los atributos especificados en las convenciones semánticas de GenAI.
Métricas
Debería ver varios registros de métricas en la salida de la consola. Tienen un aspecto similar al siguiente:
Metric Name: semantic_kernel.connectors.openai.tokens.prompt, Number of prompt tokens used, Unit: {token}, Meter: Microsoft.SemanticKernel.Connectors.OpenAI
(2024-09-12T21:48:37.9531072Z, 2024-09-12T21:48:38.0966737Z] LongSum
Value: 16
Aquí puede ver el nombre, la descripción, la unidad, el intervalo de tiempo, el tipo, el valor de la métrica y el medidor al que pertenece la métrica.
Nota:
La métrica anterior es una métrica Counter. Para obtener una lista completa de los tipos de métricas, consulte aquí. Según el tipo de métrica, la salida puede variar.
Registros
Debería ver varios registros de registro en la salida de la consola. Tienen un aspecto similar al siguiente:
{
"body": "Function SyVCcBjaULqEhItH invoking.",
"severity_number": "<SeverityNumber.INFO: 9>",
"severity_text": "INFO",
"attributes": {
"code.filepath": "C:\\tmp\\telemetry-console-quickstart\\Lib\\site-packages\\semantic_kernel\\functions\\kernel_function_log_messages.py",
"code.function": "log_function_invoking",
"code.lineno": 19
},
"dropped_attributes": 0,
"timestamp": "2024-09-13T17:55:45.504983Z",
"observed_timestamp": "2024-09-13T17:55:45.504983Z",
"trace_id": "0xe23e2c10785ea61ffc9f28be19482a80",
"span_id": "0x686bd592e27661d7",
"trace_flags": 1,
"resource": {
"attributes": {
"telemetry.sdk.language": "python",
"telemetry.sdk.name": "opentelemetry",
"telemetry.sdk.version": "1.27.0",
"service.name": "telemetry-console-quickstart"
},
"schema_url": ""
}
}
Intervalos
Debería ver varios intervalos en la salida de la consola. Tienen un aspecto similar al siguiente:
{
"name": "chat.completions gpt-4o",
"context": {
"trace_id": "0xe23e2c10785ea61ffc9f28be19482a80",
"span_id": "0x8b20e9655610c3c9",
"trace_state": "[]"
},
"kind": "SpanKind.INTERNAL",
"parent_id": "0x686bd592e27661d7",
"start_time": "2024-09-13T17:55:45.515198Z",
"end_time": "2024-09-13T17:55:46.469471Z",
"status": {
"status_code": "UNSET"
},
"attributes": {
"gen_ai.operation.name": "chat.completions",
"gen_ai.system": "openai",
"gen_ai.request.model": "gpt-4o",
"gen_ai.response.id": "chatcmpl-A74oD7WGDjawnZ44SJZrj9fKrEv1B",
"gen_ai.response.finish_reason": "FinishReason.STOP",
"gen_ai.response.prompt_tokens": 16,
"gen_ai.response.completion_tokens": 29
},
"events": [
{
"name": "gen_ai.content.prompt",
"timestamp": "2024-09-13T17:55:45.515198Z",
"attributes": {
"gen_ai.prompt": "[{\"role\": \"user\", \"content\": \"Why is the sky blue in one sentence?\"}]"
}
},
{
"name": "gen_ai.content.completion",
"timestamp": "2024-09-13T17:55:46.469471Z",
"attributes": {
"gen_ai.completion": "[{\"role\": \"assistant\", \"content\": \"The sky appears blue because shorter blue wavelengths of sunlight are scattered in all directions by the molecules and particles in the atmosphere more effectively than other colors.\"}]"
}
}
],
"links": [],
"resource": {
"attributes": {
"telemetry.sdk.language": "python",
"telemetry.sdk.name": "opentelemetry",
"telemetry.sdk.version": "1.27.0",
"service.name": "telemetry-console-quickstart"
},
"schema_url": ""
}
}
Preste atención a los atributos que comienzan por gen_ai. Estos son los atributos especificados en las convenciones semánticas de GenAI. Proporcionan información útil sobre las solicitudes enviadas a y las respuestas recibidas de los modelos de IA.
Métricas
Debería ver varios registros de métricas en la salida de la consola. Tienen un aspecto similar al siguiente:
{
"resource_metrics": [
{
"resource": {
"attributes": {
"telemetry.sdk.language": "python",
"telemetry.sdk.name": "opentelemetry",
"telemetry.sdk.version": "1.27.0",
"service.name": "telemetry-console-quickstart"
},
"schema_url": ""
},
"scope_metrics": [
{
"scope": {
"name": "semantic_kernel.functions.kernel_function",
"version": null,
"schema_url": "",
"attributes": null
},
"metrics": [
{
"name": "semantic_kernel.function.invocation.duration",
"description": "Measures the duration of a function's execution",
"unit": "s",
"data": {
"data_points": [
{
"attributes": {
"semantic_kernel.function.name": "SyVCcBjaULqEhItH"
},
"start_time_unix_nano": 1726250146470468300,
"time_unix_nano": 1726250146478526600,
"count": 1,
"sum": 0.9650602999900002,
"bucket_counts": [
0,
1,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0
],
"explicit_bounds": [
0.0,
5.0,
10.0,
25.0,
50.0,
75.0,
100.0,
250.0,
500.0,
750.0,
1000.0,
2500.0,
5000.0,
7500.0,
10000.0
],
"min": 0.9650602999900002,
"max": 0.9650602999900002
}
],
"aggregation_temporality": 2
}
}
],
"schema_url": ""
}
],
"schema_url": ""
}
]
}
La medida mostrada anteriormente es una métrica de histograma. Para obtener una lista completa de los tipos de métricas, consulte aquí.
Nota:
La observabilidad semántica del kernel aún no está disponible para Java.
Pasos siguientes
Ahora que ha generado correctamente datos de telemetría en la consola, puede obtener más información sobre cómo usar herramientas de APM para visualizar y analizar datos de telemetría.