Skip to content

TELEMETRY-INTEGRATION.md

Latest commit

 

History

History
371 lines (293 loc) · 8.34 KB

TELEMETRY-INTEGRATION.md

File metadata and controls

371 lines (293 loc) · 8.34 KB

SDK Telemetry Integration

Overview

Each generated SDK now includes unique identification and telemetry metadata that enables tracking and monitoring of SDK usage across your infrastructure.

SDK Identification

Every SDK generated includes:

  • SDK ID: Unique 32-character hexadecimal identifier (e.g., a1b2c3d4e5f6789012345678901234ab)
  • SDK Name: Human-readable name
  • SDK Version: Semantic version (e.g., 2.0.0)
  • Language: Target programming language
  • Generated At: ISO 8601 timestamp of generation
  • Telemetry Endpoint: Backend endpoint for telemetry data
  • Telemetry Enabled: Boolean flag to enable/disable telemetry

Metadata Structure

{
  "sdkId": "a1b2c3d4e5f6789012345678901234ab",
  "sdkName": "Averox Crypto SDK",
  "sdkVersion": "2.0.0",
  "language": "python",
  "generatedAt": "2025-01-21T10:12:00.000Z",
  "telemetryEndpoint": "https://telemetry.averox.io/v1/events",
  "telemetryEnabled": true,
  "metadata": {
    "generator": "FixedEnterpriseSDKGenerator",
    "generatorVersion": "2.0.0",
    "tenant": "default",
    "environment": "production"
  }
}

Implementation by Language

Python SDK

Accessing Metadata:

from averox_crypto import get_sdk_metadata

metadata = get_sdk_metadata()
print(f"SDK ID: {metadata['sdk_id']}")
print(f"SDK Version: {metadata['sdk_version']}")

Embedded in Code:

  • Constant SDK_METADATA dictionary in __init__.py
  • Function get_sdk_metadata() returns a copy of metadata

Go SDK

Accessing Metadata:

import "github.com/averox/crypto-sdk"

metadata := averox.GetSDKMetadata()
fmt.Printf("SDK ID: %s\n", metadata.SDKID)
fmt.Printf("SDK Version: %s\n", metadata.SDKVersion)

Embedded in Code:

  • Struct SDKMetadata with JSON tags
  • Function GetSDKMetadata() returns metadata struct

JavaScript/TypeScript SDK

Accessing Metadata:

import { getSDKMetadata } from '@averox/crypto-sdk';

const metadata = getSDKMetadata();
console.log(`SDK ID: ${metadata.sdkId}`);
console.log(`SDK Version: ${metadata.sdkVersion}`);

Embedded in Code:

  • Constant object exported from main module
  • Function getSDKMetadata() returns metadata object

Metadata File

Each SDK includes a .sdk-metadata file in the root directory:

# SDK Metadata
# This file contains SDK identification and telemetry configuration
# Generated: 2025-01-21T10:12:00.000Z

SDK_ID=a1b2c3d4e5f6789012345678901234ab
SDK_NAME=Averox Crypto SDK
SDK_VERSION=2.0.0
LANGUAGE=python
GENERATED_AT=2025-01-21T10:12:00.000Z
TELEMETRY_ENDPOINT=https://telemetry.averox.io/v1/events
TELEMETRY_ENABLED=true
GENERATOR=FixedEnterpriseSDKGenerator
GENERATOR_VERSION=2.0.0
TENANT=default
ENVIRONMENT=production

# JSON Format
{
  "sdkId": "a1b2c3d4e5f6789012345678901234ab",
  ...
}

Telemetry Events (Future Implementation)

Event Structure

{
  "event_type": "crypto_operation",
  "sdk_id": "a1b2c3d4e5f6789012345678901234ab",
  "sdk_version": "2.0.0",
  "language": "python",
  "timestamp": "2025-01-21T10:15:30.123Z",
  "operation": "encrypt",
  "algorithm": "aes-256-gcm",
  "mode": "envelope",
  "success": true,
  "duration_ms": 12,
  "metadata": {
    "tenant": "default",
    "environment": "production"
  }
}

Operations to Track

  1. Encryption Operations

    • Algorithm used (AES-256-GCM, ChaCha20-Poly1305)
    • Mode (standard, envelope)
    • Success/failure
    • Duration

  2. Decryption Operations

    • Algorithm used
    • Mode (standard, envelope)
    • Success/failure
    • Duration

  3. Key Operations

    • Master key generation
    • DEK requests (envelope mode)
    • DEK unwrapping (envelope mode)

  4. Error Events

    • Error type
    • Error code
    • Context

Telemetry Backend API (Future)

Endpoint: POST https://telemetry.averox.io/v1/events

Request:

{
  "events": [
    {
      "event_type": "crypto_operation",
      "sdk_id": "a1b2c3d4e5f6789012345678901234ab",
      ...
    }
  ]
}

Response:

{
  "status": "success",
  "events_received": 1
}

Configuration

Enabling/Disabling Telemetry

At Generation Time:

const sdk = {
  name: "My Crypto SDK",
  version: "2.0.0",
  telemetryEnabled: false, // Disable telemetry
  telemetryEndpoint: "https://custom-telemetry.example.com/v1/events"
};

At Runtime (Future):

from averox_crypto import configure_telemetry, NoOpTelemetry

# Disable telemetry
configure_telemetry(NoOpTelemetry())

Custom Metadata

At Generation Time:

const sdk = {
  name: "My Crypto SDK",
  version: "2.0.0",
  tenant: "acme-corp",
  environment: "staging",
  telemetryEndpoint: "https://telemetry.acme-corp.com/v1/events"
};

Privacy & Security

Data Collected

✅ Collected:

  • SDK ID (unique identifier)
  • Operation type (encrypt/decrypt)
  • Algorithm used
  • Success/failure status
  • Duration
  • Timestamp
  • Tenant/environment metadata

❌ NOT Collected:

  • Plaintext data
  • Ciphertext data
  • Encryption keys
  • AAD (Additional Authenticated Data)
  • Key IDs (unless explicitly configured)
  • User identifiable information

Compliance

  • GDPR Compliant: No personal data collected
  • SOC 2: Audit trail for security operations
  • HIPAA: No PHI collected
  • PCI DSS: No cardholder data collected

Benefits

  1. Usage Analytics

    • Track SDK adoption across organization
    • Identify most-used algorithms
    • Monitor operation success rates

  2. Performance Monitoring

    • Track operation durations
    • Identify performance bottlenecks
    • Compare performance across languages

  3. Error Tracking

    • Centralized error monitoring
    • Identify common failure patterns
    • Proactive issue detection

  4. Security Auditing

    • Track cryptographic operations
    • Detect anomalous usage patterns
    • Compliance reporting

  5. Version Management

    • Track SDK version distribution
    • Plan deprecation strategies
    • Monitor upgrade adoption

Implementation Roadmap

Phase 1: SDK Identification ✅ (Current)

  • Generate unique SDK ID
  • Embed metadata in SDK code
  • Create .sdk-metadata file
  • Implement get_sdk_metadata() functions

Phase 2: Telemetry Client (Next)

  • Implement telemetry client in each SDK
  • Add operation tracking
  • Implement batching and buffering
  • Add retry logic
  • Implement rate limiting

Phase 3: Backend Integration

  • Create telemetry backend API
  • Implement event storage
  • Create analytics dashboard
  • Add alerting system

Phase 4: Advanced Features

  • Real-time monitoring
  • Anomaly detection
  • Predictive analytics
  • Custom metrics

Example Usage

Python

from averox_crypto import AveroxCrypto, get_sdk_metadata

# Get SDK metadata
metadata = get_sdk_metadata()
print(f"Using SDK: {metadata['sdk_name']} v{metadata['sdk_version']}")
print(f"SDK ID: {metadata['sdk_id']}")

# Use SDK normally - telemetry happens automatically
crypto = AveroxCrypto(master_key)
envelope = crypto.encrypt(plaintext, aad, "key-1")

# Telemetry event sent:
# {
#   "event_type": "crypto_operation",
#   "sdk_id": "a1b2c3d4...",
#   "operation": "encrypt",
#   "algorithm": "aes-256-gcm",
#   "success": true,
#   "duration_ms": 12
# }

Go

package main

import (
    "fmt"
    averox "github.com/averox/crypto-sdk"
)

func main() {
    // Get SDK metadata
    metadata := averox.GetSDKMetadata()
    fmt.Printf("Using SDK: %s v%s\n", metadata.SDKName, metadata.SDKVersion)
    fmt.Printf("SDK ID: %s\n", metadata.SDKID)
    
    // Use SDK normally - telemetry happens automatically
    masterKey, _ := averox.GenerateMasterKey()
    crypto, _ := averox.NewAveroxCrypto(masterKey, nil)
    envelope, _ := crypto.Encrypt(plaintext, aad, "key-1", nil)
    
    // Telemetry event sent automatically
}

Monitoring Dashboard (Future)

The telemetry backend will provide a dashboard with:

  • Real-time Metrics: Operations per second, success rates
  • SDK Distribution: Versions in use, language breakdown
  • Performance Charts: Operation duration trends
  • Error Analysis: Error rates, common error types
  • Tenant Analytics: Usage by tenant/environment
  • Alerts: Anomaly detection, threshold alerts

Support

For questions about telemetry integration: