📖 Introduction

Diginsight Components are observable-first .NET libraries that bring built-in observability to common development scenarios like Azure integrations, configuration management, and data access.

Instead of adding observability as an afterthought, these components are designed from the ground up with OpenTelemetry integration, structured logging, and performance metrics built-in.

🎯 The Problem: Traditional libraries require you to manually add logging, tracing, and monitoring to understand what’s happening in production.
✨ The Solution: Diginsight Components provide the same functionality with observability already integrated.

🚀 Quick Value Proposition

🔍 Zero-Config Observability: Get detailed telemetry without writing boilerplate logging code
📊 Built-in Metrics: Automatic performance counters and business metrics (e.g., CosmosDB RU consumption)
🔗 Distributed Tracing: Full request tracing across components with OpenTelemetry
🛠️ Drop-in Replacements: Use familiar APIs with enhanced observability features
☁️ Cloud-Ready: Optimized for Azure services with built-in monitoring integration

📋 Table of Contents

💡 Why Choose Diginsight Components
🏗️ Architecture Overview
🚀 Getting Started
📦 Available Components
💼 Use Cases & Examples
📚 References

💡 Why Choose Diginsight Components

🔍 Traditional Approach vs. Diginsight Components

Without Diginsight Components:

// Manual logging and monitoring
_logger.LogInformation("Starting CosmosDB query");
var stopwatch = Stopwatch.StartNew();
try 
{
    var results = await container.GetItemQueryIterator<Product>(query).ReadNextAsync();
    _logger.LogInformation("Query completed in {Duration}ms", stopwatch.ElapsedMilliseconds);
    // Manual RU consumption tracking...
}
catch (Exception ex)
{
    _logger.LogError(ex, "Query failed");
    throw;
}

With Diginsight Components:

// Automatic observability built-in
var results = await container.GetItemQueryIteratorObservable<Product>(query).ReadNextAsync();
// ✅ Automatic logging, tracing, RU metrics, error handling

🎯 Key Benefits

⚡ Faster Development: Focus on business logic, not observability plumbing
🔍 Better Debugging: Rich telemetry helps identify issues quickly
📊 Production Insights: Built-in metrics reveal performance bottlenecks
🛡️ Reliability: Consistent error handling and retry patterns
🔄 Maintainability: Standardized observability across your entire application

🏗️ Architecture Overview

Diginsight Components follow a modular architecture with selective dependencies based on architectural roles:

┌─────────────────────────────────────────────────────────────────┐
│                      Your Application                           │
│                                                                 │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐  │
│  │ ⚙️ Configuration │  │  � Core       │  │ 🌐 Azure       │  │
│  │   Components    │  │  Components    │  │  Components    │  │
│  │                 │  │                │  │                │  │
│  │ ┌─────────────┐ │  │ ┌─────────────┐ │  │ ┌─────────────┐ │  │
│  │ │.Abstractions│ │  │ │.Abstractions│ │  │ │.Abstractions│ │  │
│  │ └─────────────┘ │  │ └─────────────┘ │  │ └─────────────┘ │  │
│  └─────────────────┘  └─────────────────┘  └─────────────────┘  │
│                                                                 │
│  ┌─────────────────┐                                            │
│  │ 🎨 Presentation │     ← Choose only what you need            │
│  │   Components    │                                            │
│  │                 │                                            │
│  │ ┌─────────────┐ │                                            │
│  │ │.Abstractions│ │                                            │
│  │ └─────────────┘ │                                            │
│  └─────────────────┘                                            │
└─────────────────────────────────────────────────────────────────┘

Dependency Architecture

The diagram above shows a simplified view. In reality, the architecture has strategic dependencies:

⚙️ Configuration Components (Orchestrator)
├── 🌐 Azure Components (domain-specific, independent from each other)
├── 🎨 Presentation Components (domain-specific, independent from each other)
└── 🎯 Core Components (Foundation)
       (all components depend on Core)

Key Architectural Principles

🧩 Selective Modularity: Components have strategic dependencies based on their architectural role
🎯 Core Foundation: Diginsight.Components provides foundational utilities that all components can use
⚙️ Configuration Orchestration: Configuration components can use and configure all other components
🌐 Domain Independence: Domain-specific components (Azure, Presentation) are independent from each other
🔌 Abstractions Pattern: Every component comes with its .Abstractions assembly for clean dependency injection
📊 Observable by Default: Every component includes built-in telemetry and metrics

⚙️ Configuration Components Orchestration

Diginsight.Components.Configuration provides configurable activation capabilities:

🌐 Cross-Component Configuration: Can configure and activate features across different component assemblies
📋 Centralized Activation: Provides configurable activation capabilities for various components
🔧 Component Orchestration: Manages startup, initialization, and configuration of other components
🎛️ Feature Toggles: Enables/disables component features through configuration

// based on appsettings-json configuration, 
// Configuration Components activate observability for all other components
services.AddObservability(configuration, hostEnvironment, out IOpenTelemetryOptions openTelemetryOptions);

Component Assembly Pattern

Each functional area provides two assemblies:

Diginsight.Components.{Area} - Implementation with observable extensions
Diginsight.Components.{Area}.Abstractions - Interfaces and contracts for DI

This allows you to:

Reference only abstractions in your domain layer
Reference implementations in your composition root
Test easily with clean interfaces
Avoid circular dependencies

🚀 Getting Started

📦 Installation

Install the components you need via NuGet:

# For enhanced configuration
dotnet add package Diginsight.Components.Configuration

# For Azure services (CosmosDB, Tables, etc.)
dotnet add package Diginsight.Components.Azure

# For core utilities
dotnet add package Diginsight.Components

⚙️ Basic Setup

// Program.cs or Startup.cs
builder.Services.AddDiginsightConfiguration()
                .AddDiginsightAzure()
                .AddOpenTelemetry(); // Automatic observability

🎯 Your First Observable Operation

// Instead of regular CosmosDB client
var results = await container.GetItemQueryIteratorObservable<Product>(
    "SELECT * FROM c WHERE c.category = @category"
).ReadNextAsync();

// ✅ Automatically provides:
// - Distributed tracing spans
// - RU consumption metrics  
// - Query performance logging
// - Error tracking and correlation

📦 Available Components

Components are organized by functionality and include both implementation and abstraction packages for clean dependency injection.

⚙️ Configuration Components

Cross-cutting configuration management with component activation capabilities

`Diginsight.Components.Configuration`

Purpose: Cross-component configuration orchestrator that provides enhanced .NET configuration with observability and component activation
Key Features:
- 🔐 Azure Key Vault Integration: Automatic authentication and secret management
- 🎛️ Component Activation: Configurable activation of other Diginsight components
- 📋 Startup Diagnostics: Configuration troubleshooting and validation
- 🌍 Environment-Specific Config: Support for .local, .environment files
- 📊 Configuration Observability: Full visibility into configuration sources and values
- 🔧 Cross-Component Settings: Centralized configuration for Azure, Core, and Presentation components
Use Cases:
- Applications requiring centralized configuration management
- Multi-component applications needing coordinated activation
- Secure configuration with Azure Key Vault integration
- Development environments with local configuration overrides

`Diginsight.Components.Configuration.Abstractions`

Purpose: Interfaces and contracts for configuration orchestration
Key Features: Configuration provider interfaces, component activation contracts, cross-cutting configuration patterns

🎯 Core Components

Essential functionality with built-in observability

`Diginsight.Components`

Purpose: Common utilities with observable patterns
Key Features:
- 🌐 Observable HTTP client configuration
- 🔐 Authentication and JWT token handling with telemetry
- 🛡️ Cryptography support with operation tracking
- ⚙️ Microsoft Identity integration
Use Cases: Any application needing HTTP clients, authentication, or security features

`Diginsight.Components.Abstractions`

Purpose: Core interfaces for all components
Key Features: IDebugService interface, base contracts, common patterns

🌐 Azure Components

Azure services with built-in observability and advanced metrics

`Diginsight.Components.Azure`

Purpose: Observable Azure service integrations
Key Features:
- 📊 CosmosDB Extensions: Query operations with RU consumption metrics, performance tracking
- 🗄️ Azure Table Extensions: Table operations with built-in observability
- ☁️ Other Azure Services: Observable patterns for various Azure APIs
Use Cases: Applications using Azure data services needing performance insights

`Diginsight.Components.Azure.Abstractions`

Purpose: Interfaces for Azure service integrations
Key Features: Base contracts for Azure observable extensions

🎨 Presentation Components

UI and API layer components (In Development)

`Diginsight.Components.Presentation`

Purpose: UI/API specific observability features
Status: Currently in development
Planned Features: MVC/API telemetry, request/response tracking, user journey analytics

💼 Use Cases & Examples

🏢 Enterprise Application

// Full stack observability
builder.Services
    .AddDiginsightConfiguration()  // 📋 Observable configuration
    .AddDiginsightAzure()          // ☁️ Azure service telemetry
    .AddDiginsightPresentation();  // 🎨 API/UI observability

🚀 Microservice with CosmosDB

// Focus on Azure data services
builder.Services
    .AddDiginsightConfiguration()
    .AddDiginsightAzure();

// Your service gets automatic observability
public class ProductService
{
    public async Task<Product> GetProductAsync(string id)
    {
        // Automatic: tracing, logging, RU metrics, error handling
        return await _container.ReadItemObservableAsync<Product>(id, new PartitionKey(id));
    }
}

🛠️ Development & Debugging

// Enhanced configuration for local development
builder.Configuration
    .AddDiginsightConfiguration()  // Loads .local files, enables debug logging
    .AddKeyVault();                // Connects to dev Key Vault automatically

📚 References

📘 Diginsight Documentation

Diginsight Telemetry - Core observability platform
Diginsight Smartcache - Hybrid caching strategies
Diginsight GitHub - Source code and examples

🔭 OpenTelemetry & Observability

OpenTelemetry .NET - .NET observability standards
Azure Monitor - Azure observability platform
Distributed Tracing - Tracing concepts

☁️ Azure & .NET Technologies

Azure Cosmos DB - Document database service
Azure Key Vault - Secrets management
.NET Configuration - Configuration patterns
ASP.NET Core - Web framework