Configuration

The Shinzo TypeScript SDK provides extensive configuration options to customize telemetry collection, data processing, and export behavior for your MCP server.

Basic Configuration

The minimal configuration requires only a few essential parameters:

import { instrumentServer } from "@shinzolabs/instrumentation-mcp"

const telemetry = instrumentServer(server, {
  serverName: "my-mcp-server",
  serverVersion: "1.0.0",
  exporterEndpoint: "https://api.app.shinzo.ai/telemetry/ingest_http",
  exporterAuth: {
    type: "bearer",
    token: "your-ingest-token-here"
  }
})

TelemetryConfig Interface

The TelemetryConfig interface provides comprehensive configuration options:

Required Parameters

Parameter	Type	Description
`serverName`	`string`	Name of your MCP server
`serverVersion`	`string`	Version of your MCP server

Export Configuration

Parameter	Type	Default	Description
`exporterEndpoint`	`string`	-	OpenTelemetry collector endpoint URL
`exporterType`	`'otlp-http' \| 'otlp-grpc' \| 'console'`	`'otlp-http'`	Type of telemetry exporter
`exporterAuth`	`ExporterAuth`	-	Authentication configuration

Data Collection

Parameter	Type	Default	Description
`enableTracing`	`boolean`	`true`	Enable trace collection
`enableMetrics`	`boolean`	`true`	Enable metrics collection
`enableArgumentCollection`	`boolean`	`false`	Collect tool arguments in traces
`samplingRate`	`number`	`1.0`	Trace sampling rate (0.0 to 1.0)

Privacy & Processing

Parameter	Type	Default	Description
`enablePIISanitization`	`boolean`	`true`	Enable automatic PII sanitization
`PIISanitizer`	`PIISanitizer`	-	Custom PII sanitizer instance
`dataProcessors`	`((data: any) => any)[]`	`[]`	Custom data processing functions

Performance

Parameter	Type	Default	Description
`metricExportIntervalMs`	`number`	`5000`	Metric export interval in milliseconds
`batchTimeoutMs`	`number`	`2000`	Batch timeout in milliseconds

Authentication Configuration

Bearer Token Authentication (required for the Shinzo Platform)

const telemetry = instrumentServer(server, {
  serverName: "my-server",
  serverVersion: "1.0.0",
  exporterEndpoint: "https://api.app.shinzo.ai/telemetry/ingest_http",
  exporterAuth: {
    type: "bearer",
    token: process.env.TOKEN
  }
})

API Key Authentication

const telemetry = instrumentServer(server, {
  serverName: "my-server",
  serverVersion: "1.0.0",
  exporterEndpoint: "https://custom-endpoint.com/v1",
  exporterAuth: {
    type: "apiKey",
    apiKey: process.env.API_KEY
  }
})

Basic Authentication

const telemetry = instrumentServer(server, {
  serverName: "my-server",
  serverVersion: "1.0.0",
  exporterEndpoint: "https://custom-endpoint.com/v1",
  exporterAuth: {
    type: "basic",
    username: process.env.USERNAME,
    password: process.env.PASSWORD
  }
})

Exporter Types

OTLP HTTP Exporter (Default)

const telemetry = instrumentServer(server, {
  serverName: "my-server",
  serverVersion: "1.0.0",
  exporterType: "otlp-http",
  exporterEndpoint: "https://api.app.shinzo.ai/telemetry/ingest_http",
  exporterAuth: ...
})

OTLP gRPC Exporter

const telemetry = instrumentServer(server, {
  serverName: "my-server",
  serverVersion: "1.0.0",
  exporterType: "otlp-grpc",
  exporterEndpoint: "https://api.app.shinzo.ai/telemetry/ingest_grpc",
  exporterAuth: ...
})

Console Exporter (Development)

Perfect for development and debugging:

const telemetry = instrumentServer(server, {
  serverName: "my-server",
  serverVersion: "1.0.0",
  exporterType: "console",
  enableMetrics: false, // Console exporter doesn't support metrics
  samplingRate: 1.0 // Sample all traces in development
})

Privacy Configuration

Built-in PII Sanitization

The SDK automatically detects and sanitizes common PII patterns:

const telemetry = instrumentServer(server, {
  serverName: "my-server",
  serverVersion: "1.0.0",
  exporterEndpoint: "https://api.app.shinzo.ai/telemetry/ingest_http",
  enablePIISanitization: true, // Default
  exporterAuth: {
    type: "bearer",
    token: process.env.SHINZO_TOKEN
  }
})

Custom PII Sanitizer

Implement your own PII sanitization logic:

import { PIISanitizer } from "@shinzolabs/instrumentation-mcp"

class CustomPIISanitizer implements PIISanitizer {
  sanitize(data: any): any {
    // Your custom sanitization logic
    if (typeof data === 'string') {
      return data.replace(/\b\d{4}-\d{4}-\d{4}-\d{4}\b/g, '****-****-****-****')
    }
    return data
  }
}

const telemetry = instrumentServer(server, {
  serverName: "my-server",
  serverVersion: "1.0.0",
  exporterEndpoint: "https://api.app.shinzo.ai/telemetry/ingest_http",
  PIISanitizer: new CustomPIISanitizer(),
  exporterAuth: {
    type: "bearer",
    token: process.env.SHINZO_TOKEN
  }
})

Data Processing

Custom Data Processors

Add custom logic to process telemetry data before export:

const telemetry = instrumentServer(server, {
  serverName: "my-server",
  serverVersion: "1.0.0",
  exporterEndpoint: "https://api.app.shinzo.ai/telemetry/ingest_http",
  dataProcessors: [
    // Remove sensitive tool arguments
    (data) => {
      if (data['mcp.tool.name'] === 'sensitive_operation') {
        for (const key of Object.keys(data)) {
          if (key.startsWith('mcp.request.argument')) {
            delete data[key]
          }
        }
      }
      return data
    },

    // Add custom metadata
    (data) => {
      data['environment'] = process.env.NODE_ENV || 'development'
      data['deployment.version'] = process.env.DEPLOYMENT_VERSION
      return data
    },

    // Filter out health check spans
    (data) => {
      if (data['mcp.tool.name'] === 'health_check') {
        return null // Return null to skip this data
      }
      return data
    }
  ],
  exporterAuth: {
    type: "bearer",
    token: process.env.SHINZO_TOKEN
  }
})

Sampling Configuration

Fixed Sampling Rate

const telemetry = instrumentServer(server, {
  serverName: "my-server",
  serverVersion: "1.0.0",
  exporterEndpoint: "https://api.app.shinzo.ai/telemetry/ingest_http",
  samplingRate: 0.1, // Sample 10% of traces
  exporterAuth: {
    type: "bearer",
    token: process.env.SHINZO_TOKEN
  }
})

Environment-based Sampling

const getSamplingRate = () => {
  switch (process.env.NODE_ENV) {
    case 'production': return 0.05 // 5% in production
    case 'staging': return 0.25    // 25% in staging
    case 'development': return 1.0 // 100% in development
    default: return 0.1            // 10% default
  }
}

const telemetry = instrumentServer(server, {
  serverName: "my-server",
  serverVersion: "1.0.0",
  exporterEndpoint: "https://api.app.shinzo.ai/telemetry/ingest_http",
  samplingRate: getSamplingRate(),
  exporterAuth: {
    type: "bearer",
    token: process.env.SHINZO_TOKEN
  }
})

Performance Tuning

Batch Configuration

const telemetry = instrumentServer(server, {
  serverName: "my-server",
  serverVersion: "1.0.0",
  exporterEndpoint: "https://api.app.shinzo.ai/telemetry/ingest_http",
  batchTimeoutMs: 1000,        // Export every 1 second
  metricExportIntervalMs: 10000, // Export metrics every 10 seconds
  exporterAuth: {
    type: "bearer",
    token: process.env.SHINZO_TOKEN
  }
})

Memory Optimization

For high-throughput servers:

const telemetry = instrumentServer(server, {
  serverName: "my-server",
  serverVersion: "1.0.0",
  exporterEndpoint: "https://api.app.shinzo.ai/telemetry/ingest_http",
  samplingRate: 0.01,           // Low sampling rate
  enableArgumentCollection: false, // Skip argument collection
  batchTimeoutMs: 500,          // Frequent exports
  exporterAuth: {
    type: "bearer",
    token: process.env.SHINZO_TOKEN
  }
})

Environment-Specific Configuration

Development Configuration

const isDevelopment = process.env.NODE_ENV === 'development'

const telemetry = instrumentServer(server, {
  serverName: "my-server",
  serverVersion: "1.0.0",
  exporterType: isDevelopment ? "console" : "otlp-http",
  exporterEndpoint: isDevelopment ? undefined : "https://api.app.shinzo.ai/telemetry/ingest_http",
  enableMetrics: !isDevelopment, // Disable metrics for console output
  samplingRate: isDevelopment ? 1.0 : 0.1,
  enableArgumentCollection: isDevelopment,
  exporterAuth: isDevelopment ? undefined : {
    type: "bearer",
    token: process.env.SHINZO_TOKEN
  }
})

Production Configuration

const telemetry = instrumentServer(server, {
  serverName: "my-server",
  serverVersion: process.env.APP_VERSION || "1.0.0",
  exporterEndpoint: "https://api.app.shinzo.ai/telemetry/ingest_http",
  exporterAuth: {
    type: "bearer",
    token: process.env.SHINZO_TOKEN
  },
  samplingRate: 0.05,
  enableArgumentCollection: false,
  enablePIISanitization: true,
  batchTimeoutMs: 2000,
  metricExportIntervalMs: 30000,
  dataProcessors: [
    (data) => {
      data['environment'] = 'production'
      data['service.instance.id'] = process.env.HOSTNAME
      return data
    }
  ]
})

Configuration Validation

The SDK validates configuration at startup and will log warnings for common issues:

Missing required parameters
Invalid sampling rates (must be between 0.0 and 1.0)
Incompatible exporter/configuration combinations
Network connectivity issues

TypeScript SDK

Python SDK

​Configuration

​Basic Configuration

​TelemetryConfig Interface

​Required Parameters

​Export Configuration

​Data Collection

​Privacy & Processing

​Performance

​Authentication Configuration

​Bearer Token Authentication (required for the Shinzo Platform)

​API Key Authentication

​Basic Authentication

​Exporter Types

​OTLP HTTP Exporter (Default)

​OTLP gRPC Exporter

​Console Exporter (Development)

​Privacy Configuration

​Built-in PII Sanitization

​Custom PII Sanitizer

​Data Processing

​Custom Data Processors

​Sampling Configuration

​Fixed Sampling Rate

​Environment-based Sampling

​Performance Tuning

​Batch Configuration

​Memory Optimization

​Environment-Specific Configuration

​Development Configuration

​Production Configuration

​Configuration Validation