CerbiStream 1.1.19

CerbiStream: Dev-Friendly, Governance-Enforced Logging for .NET

Brought to you by Cerbi LLC, your trusted partner in enterprise observability.

🚀 View CerbiStream Benchmarks Compare against Serilog, NLog, and others. CerbiStream is engineered for high performance, strict governance, and enterprise-grade log routing.

🔗 Supported Destinations

CerbiStream can route logs to:

• Queues: Azure Service Bus, RabbitMQ, Kafka, AWS SQS/Kinesis, Google Pub/Sub
• HTTP Endpoints: Any REST API with custom headers
• Cloud Storage: Azure Blob, AWS S3, Google Cloud Storage
• File Fallback: Local JSON file (AES/Base64 encryption supported)
• Telemetry Providers: App Insights, OpenTelemetry, Datadog, AWS CloudWatch, GCP Stackdriver

🧱 CerbiSuite Overview

📚 Table of Contents

• Overview
• Highlights
• Developer Quick Start
• Advanced Setup & Best Practices
• Configuration Options
• Features
• Governance and Compliance
• Advanced Metadata & Encryption
• Usage Examples
• Integration & Supported Platforms
• Telemetry Provider Support
• Benchmark vs Serilog
• Unit Testing
• Contributing
• Community & Support
• License

🆕 2025 Governance Update

CerbiStream now uses real-time governance enforcement via Cerbi.Governance.Runtime, removing most limitations of build-time validation.

✅ Runtime Advantages:

• Compatible with .NET 6–8+
• Config from local, blob, or GitHub
• Automatically tags logs with governance info
• Supports .Relax() and [CerbiTopic]

⚠️ Build-Time Analyzer Limitations:

• Requires local files and static references
• Not compatible with CI or dynamic config

🔄 Recent Updates (v1.1.16)

• ✅ Async console logging via Channel<string>

  • Dramatically improves performance during high-volume console logging
  • Enable using .WithAsyncConsoleOutput(true)
  • Automatically wired via AddCerbiStream(...)

• Unified enrichment with LogId, ApplicationId, InstanceId, etc.

• Full-payload encryption using AES or Base64

• File fallback with encryption support (AES/Base64)

• Queue + cloud routing (HTTP, Blob, etc.)

• Built-in governance validation via Cerbi.Governance.Runtime

• Topic tagging with [CerbiTopic] and relaxed logging via .Relax()

Here is the updated README section that includes your new async console logging support. This makes it clear to developers that CerbiStream supports background-buffered logging for high-performance scenarios, just like Serilog's async sink:

CerbiStream now supports async console output using a high-performance background channel dispatcher. This significantly improves logging throughput, especially during bursts or heavy load.

✅ Runtime Enhancements

• Async Console Dispatch: Offloads Console.WriteLine to a background thread using Channel<string> — 10x+ faster under load.
• Enable via Fluent API: .WithAsyncConsoleOutput(true)
• Auto-wired via AddCerbiStream(...): No boilerplate needed in Program.cs
• Compatible with Relax() and governance enforcement
• Zero impact on telemetry, queue, or file fallback behavior

builder.Logging.AddCerbiStream(options =>
{
    options.WithAsyncConsoleOutput(true)
           .WithGovernanceChecks(true)
           .EnableDeveloperModeWithoutTelemetry();
});

🔧 This uses the same async model as Serilog.Sinks.Async for performance, ensuring non-blocking log flow even when console is enabled.

📈 Performance Impact

CerbiStream with async console enabled matches or exceeds Serilog's async throughput for console scenarios.

Developer Quick Start

👉 Quick Start Guide

🧰 Developer Setup Matrix

🔹 Basic Development (No Governance)

builder.Logging.AddCerbiStream(options =>
{
    options.EnableDevModeMinimal();
});

🔸 Development with Real-Time Governance

builder.Logging.AddCerbiStream(options =>
{
    options.WithFileFallback("cerbi_fallback.json")
           .WithGovernanceChecks(true)
           .WithGovernanceProfile("default")
           .EnableDeveloperModeWithoutTelemetry();
});

🟢 Development with Governance + Telemetry

builder.Logging.AddCerbiStream(options =>
{
    options.WithQueue("AzureServiceBus", "Endpoint=sb://...", "log-queue")
           .WithEncryptionMode(EncryptionType.Base64)
           .WithGovernanceChecks(true)
           .WithTelemetryProvider(
               TelemetryProviderFactory.CreateTelemetryProvider("appinsights")
           )
           .EnableDeveloperModeWithTelemetry();
});

---

## Advanced Setup & Best Practices

👉 [Advanced Setup Guide](LoggingStandards/README-CerbiStream–AdvancedSetup&BestPractices.md)

---

## Overview

CerbiStream is a developer-first logging library built for performance, security, and governance enforcement.

---

## Highlights

- Async, queue-first architecture
- Flexible encryption
- Runtime governance validation
- Low object allocation
- Azure/GCP/AWS-aware metadata

---

## ⚙️ Configuration Options

- `.WithQueue(...)`
- `.WithEncryptionMode(...)`
- `.WithFileFallback(...)`
- `.WithGovernanceChecks(...)`
- `.EnableDeveloperModeWithTelemetry()`

### Encryption Types
- `None`
- `Base64`
- `AES`

### Config Sources
- Local JSON
- Azure Blob / AWS S3 / GCP
- GitHub raw URL

---

## Features

- Topic-based log scoping
- Metadata injection
- Governance policy validation
- Relaxed log support
- Queue & blob transport
- Polly retry support

---

## Governance and Compliance

- Runtime enforcement with `Cerbi.Governance.Runtime`
- Analyzer available for CI validation
- Tags include `GovernanceProfileUsed`, `GovernanceViolations`, etc.

---

## Advanced Metadata & Encryption

```csharp
options.WithMetadataInjection(true)
       .WithEncryptionMode(EncryptionType.AES)
       .WithEncryptionKey(key, iv);

JSON logs are fully encrypted before sending.

Usage Examples

• Relaxed logging: logger.Relax()
• Topic assignment: [CerbiTopic("Payments")]
• Fallback to file: .WithFileFallback("fallback.json")
• Multi-cloud: auto-populates cloud provider

🔓 Relaxed Logging Modes

Cerbi supports two forms of relaxed logging to bypass governance rules when explicitly intended:

Mode Description Usage Example Fluent .Relax() Developer-triggered, scoped for individual log statements logger.Relax().LogInformation("...") Runtime .RelaxGovernance() Global override, wraps logger during startup configuration logger = logger.RelaxGovernance();

🧑‍💻 Developer Inline (Fluent API):

var logger = builder.Logging.CreateLogger("MyApp");
logger = logger.RelaxGovernance(); // All logs now include GovernanceRelaxed: true

This uses CerbiLoggerWrapper for structured logging, useful during development or for logs intentionally excluded from governance enforcement.

⚙️ Runtime Setup Override:

var logger = builder.Logging.CreateLogger("MyApp");
logger = logger.RelaxGovernance(); // All logs now include GovernanceRelaxed: true

Integration & Supported Platforms

• Queues: RabbitMQ, Azure, Kafka, etc.
• HTTP REST APIs
• Azure Blob, AWS S3, GCP Storage
• Auto-detect metadata from cloud env vars

Telemetry Provider Support

Benchmark vs Serilog

Unit Testing

Covers:

• Governance rule enforcement
• Retry/backoff
• Metadata injection
• Fallback logging rotation
• Encryption and validation

Contributing

PRs welcome! Please open an issue first for large features. Follow code style and ensure tests pass.

Community & Support

• GitHub: https://github.com/Zeroshi/Cerbi-CerbiStream
• Email: hello@cerbi.io
• Website: https://cerbi.io
• Benchmarks: https://cerbi.systems

📌 Under the Hood: Runtime Defaults & Utilities

   ┌────────┐
   │  log   │
   └───┬────┘
       │
       ▼
  ┌──────────┐
  │ enrich   │◄───┐
  └────┬─────┘    │
       ▼          │
  ┌──────────┐     │
  │ encrypt  │     │
  └────┬─────┘     │
       ▼          │
  ┌──────────┐     │
  │ validate │     │
  └────┬─────┘     │
       ▼          │
  ┌──────────┐     │
  │  send    │─────┘
  └──────────┘
       ▲
       │
  ┌──────────────┐
  │ RetryPolicy  │
  └──────────────┘

CerbiStream includes helpful built-in utilities and conventions:

☁️ Cloud Metadata Detection

Pulled from environment variables using ApplicationMetadata:

• CloudProvider resolves from AWS, Azure, or GCP.
• Region is inferred from cloud-specific variables.
• InstanceId and ApplicationVersion are auto-filled.

🛠️ Central Config Convenience

Use CerbiStreamConfig for:

• Single-file config initialization
• Auto-detected cloud + env context
• Runtime feature toggles (e.g., encryption, telemetry)

🔁 Retry Behavior

Retry logic for queue delivery is powered by Polly:

RetryPolicyFactory.Create(3, 200); // Retries 3x with 200ms delay

This is used when .WithQueueRetries(...) is enabled.

📡 Telemetry Integration

Quickly wire up telemetry providers with:

TelemetryProviderFactory.CreateTelemetryProvider("appinsights");

Supported options include AppInsights, OpenTelemetry, Datadog, AWS CloudWatch, and GCP Stackdriver.

Here’s the addition you can include in your README.md under a new section like ## 🙏 Acknowledgments or within your ## 🔄 Recent Updates or ## 🧪 Benchmarks section:

🙏 Acknowledgments

Special thanks to @snakefoot for the performance insights and benchmark contributions across popular logging frameworks:

• ✅ Microsoft Console Logger uses an asynchronous queue by default.
• ⚠️ Serilog Console writes synchronously — causing slower results unless async sinks are used.
• ✅ NLog and Log4Net support async file targets out of the box, yielding faster logging performance.
• 🧪 These contributions helped improve CerbiStream's own async capabilities.

Let me know if you'd like this rendered into a Markdown table with benchmark chart screenshots or badges.

License

MIT © Cerbi LLC