Logging and Tracing

Effective logging and tracing are essential for monitoring, debugging, and optimizing AgentScope AI deployments. This document outlines best practices for implementing logging and tracing mechanisms in AgentScope AI to ensure operational visibility, quick issue resolution, and performance optimization.

Logging in AgentScope AI

Logging provides a record of events that occur during the execution of agents, workflows, and tools. AgentScope AI supports structured logging to capture key system activities, errors, and performance metrics.

Setting Up Logging

AgentScope AI uses Winston as its default logging library, but you can integrate other logging systems like Pino, Bunyan, or Log4js based on your needs.

Installing Winston (Default Logger)

npm install winston

Configuring a Logger

import winston from 'winston';

const logger = winston.createLogger({
  level: 'info',
  format: winston.format.combine(
    winston.format.timestamp(),
    winston.format.json()
  ),
  transports: [
    new winston.transports.Console(),
    new winston.transports.File({ filename: 'logs/agentscope.log' })
  ],
});

export default logger;

Logging Events in an Agent

import logger from '../logger';

export const exampleAgent = async (input: string) => {
  logger.info(`Agent received input: ${input}`);
  try {
    const result = await processInput(input);
    logger.info(`Agent successfully processed input: ${result}`);
    return result;
  } catch (error) {
    logger.error(`Agent encountered an error: ${error.message}`);
    throw error;
  }
};

Log Levels

• info – General operational messages.

• warn – Warnings that need attention.

• error – Errors that require investigation.

• debug – Detailed logs for debugging purposes.

Tracing in AgentScope AI

Tracing enables tracking the flow of execution across different services and components in a distributed system. AgentScope AI supports OpenTelemetry for distributed tracing.

Setting Up OpenTelemetry

Installing Required Packages

npm install @opentelemetry/api @opentelemetry/node @opentelemetry/tracing @opentelemetry/exporter-jaeger

Configuring Tracing

import { NodeTracerProvider } from '@opentelemetry/node';
import { SimpleSpanProcessor } from '@opentelemetry/tracing';
import { JaegerExporter } from '@opentelemetry/exporter-jaeger';

const provider = new NodeTracerProvider();
const exporter = new JaegerExporter({ serviceName: 'AgentScopeAI' });

provider.addSpanProcessor(new SimpleSpanProcessor(exporter));
provider.register();

export const tracer = provider.getTracer('agentscope-ai-tracer');

Adding Tracing to an Agent

import { tracer } from '../tracing';

export const exampleAgentWithTracing = async (input: string) => {
  const span = tracer.startSpan('exampleAgentWithTracing');
  try {
    span.setAttribute('input', input);
    const result = await processInput(input);
    span.setAttribute('output', result);
    return result;
  } catch (error) {
    span.recordException(error);
    throw error;
  } finally {
    span.end();
  }
};

Integration with Monitoring Platforms

Log Management

• Datadog: AgentScope AI logs can be forwarded to Datadog for centralized log analysis.

• ELK Stack: Logs can be stored and visualized using Elasticsearch, Logstash, and Kibana.

Tracing Visualization

• Jaeger: OpenTelemetry traces can be sent to Jaeger for visualization and analysis.

• Zipkin: Another alternative for distributed tracing storage and visualization.

Best Practices

1. Use structured logging – Ensure logs are in JSON format for easy processing.

2. Set appropriate log levels – Avoid excessive logging in production environments.

3. Correlate logs with traces – Use unique identifiers to link logs and traces for better debugging.

4. Centralized logging and monitoring – Use cloud-based or on-premise solutions to aggregate logs and traces.

5. Redact sensitive information – Avoid logging user credentials or personal data.