Serilog.Enrichers.Amazon 1.0.0-ci-20250706-015808

AWS Elastic Beanstalk Enricher for Serilog

A powerful Serilog enricher that automatically adds AWS Elastic Beanstalk environment information to all log events, providing rich contextual metadata for cloud-native applications.

Brought to you by Sustainment.com - Making American Manufacturing Great Again!

🚀 Features

• Automatic Enrichment: Seamlessly adds Beanstalk metadata to every log event
• Rich Context: Includes application name, environment name, instance ID, version, and more
• Multi-Framework Support: Targets .NET 8, 9, and 10
• Dependency Injection: Integrates cleanly with .NET DI container
• Performance Optimized: Leverages cached environment detection for minimal overhead
• Structured Logging: Adds strongly-typed properties for better log analysis
• Zero Configuration: Works out-of-the-box when properly registered

📦 Installation

Install via NuGet Package Manager:

dotnet add package Serilog.Enrichers.Amazon

Or via Package Manager Console:

Install-Package Serilog.Enrichers.Amazon

🔧 Quick Start

Basic Setup with Dependency Injection

using Serilog;
using Sustainment.Extensions.Configuration.Amazon;

var builder = WebApplication.CreateBuilder(args);

// 1. Add AWS Beanstalk configuration provider
builder.Configuration.AddEC2MetadataConfiguration();

// 2. Register AWS enrichment services
builder.Services.AddAmazonSerilogEnrichment(builder.Configuration);

// 3. Configure Serilog with Beanstalk enrichment
builder.Host.UseSerilog((context, services, configuration) =>
{
    configuration
        .ReadFrom.Configuration(context.Configuration)
        .Enrich.WithElasticBeanstalk(services)
        .WriteTo.Console();
});

var app = builder.Build();

⚡ Performance Optimization

For fastest startup times, set this environment variable in your Beanstalk environment:

elasticbeanstalk_environment_name=your-environment-name

This enables instant detection and eliminates network calls during startup.

🛠 How It Works

The enricher automatically adds the following properties to every log event:

Log Properties Added

Environment Details Structure

The aws.beanstalk property contains a structured object with:

{
  "ApplicationName": "my-web-app",
  "EnvironmentName": "production",
  "InstanceId": "i-1234567890abcdef0",
  "VersionLabel": "v1.2.3",
  "EnvironmentArn": "arn:aws:elasticbeanstalk:us-west-2:123456789012:environment/my-web-app/production",
  "PlatformArn": "arn:aws:elasticbeanstalk:us-west-2::platform/...",
  "Cname": "myapp.us-west-2.elasticbeanstalk.com",
  "Health": "Ok",
  "Status": "Ready",
  "DateCreated": "2023-01-15T10:30:00Z",
  "DateUpdated": "2023-01-20T14:45:00Z"
}

🔍 Usage Examples

Complete Setup Example

using Serilog;
using Sustainment.Extensions.Configuration.Amazon;

var builder = WebApplication.CreateBuilder(args);

// Configuration and services setup
builder.Configuration.AddEC2MetadataConfiguration();
builder.Services.AddAmazonSerilogEnrichment(builder.Configuration);

// Serilog configuration
builder.Host.UseSerilog((context, services, loggerConfig) =>
{
    loggerConfig
        .ReadFrom.Configuration(context.Configuration)
        .Enrich.WithElasticBeanstalk(services)
        .WriteTo.Console(outputTemplate: 
            "[{Timestamp:HH:mm:ss} {Level:u3}] {Message:lj} " +
            "{aws.beanstalk.ApplicationName}:{aws.beanstalk.EnvironmentName}:{version} {NewLine}{Exception}")
        .WriteTo.File("logs/app.log", 
            outputTemplate: "{Timestamp:yyyy-MM-dd HH:mm:ss.fff zzz} [{Level:u3}] {Message:lj} {Properties:j}{NewLine}{Exception}");
});

var app = builder.Build();

// Your application code
app.MapGet("/", (ILogger<Program> logger) =>
{
    logger.LogInformation("Hello from Beanstalk!");
    return "Hello World!";
});

app.Run();

Sample Log Output

With the enricher active, your logs will include rich AWS context:

[14:30:15 INF] Processing user request my-web-app:production:v1.2.3
[14:30:16 INF] Order completed successfully my-web-app:production:v1.2.3

JSON structured output:

{
  "@timestamp": "2023-01-20T14:30:15.123Z",
  "level": "Information",
  "message": "Processing user request",
  "aws": {
    "beanstalk": {
      "ApplicationName": "my-web-app",
      "EnvironmentName": "production",
      "InstanceId": "i-1234567890abcdef0",
      "VersionLabel": "v1.2.3",
      "EnvironmentArn": "arn:aws:elasticbeanstalk:us-west-2:123456789012:environment/my-web-app/production",
      "Health": "Ok",
      "Status": "Ready"
    }
  },
  "version": "v1.2.3"
}

Custom Log Templates

Console with AWS context:

.WriteTo.Console(outputTemplate: 
    "[{Timestamp:HH:mm:ss} {Level:u3}] {Message:lj} " +
    "| App: {aws.beanstalk.ApplicationName} | Env: {aws.beanstalk.EnvironmentName} | Ver: {version} {NewLine}{Exception}")

File with full JSON context:

.WriteTo.File("logs/app.log", 
    formatter: new JsonFormatter())

🌍 Environment Setup

🚀 Production Deployment (Recommended)

Set this in your Beanstalk environment configuration for optimal performance:

elasticbeanstalk_environment_name=your-production-environment-name

How to set in Beanstalk:

1. Go to your Beanstalk environment
2. Configuration → Software → Environment properties
3. Add: elasticbeanstalk_environment_name = your-environment-name

🏠 Local Development Setup

# Skip AWS detection during local development
export elasticbeanstalk_environment_islocal=true

Local Testing with Mock Data

// For local development, you can register mock environment details
if (!EC2MetadataConfigurationProvider.IsRunningOnBeanstalk())
{
    builder.Services.AddSingleton(new EnvironmentDetails
    {
        ApplicationName = "my-app-local",
        EnvironmentName = "development",
        VersionLabel = "dev-build",
        InstanceId = "local-machine"
    });
}

🏗 Advanced Configuration

Manual Enricher Registration

If you prefer manual configuration without the extension methods:

var environmentDetails = new EnvironmentDetails(); // Configure manually
builder.Configuration.GetSection("elasticbeanstalk").Bind(environmentDetails);

builder.Services.AddSingleton(environmentDetails);
builder.Services.AddSingleton<ElasticBeanstalkEnricher>();

builder.Host.UseSerilog((context, services, configuration) =>
{
    configuration
        .Enrich.WithElasticBeanstalk(services)
        .WriteTo.Console();
});

Conditional Enrichment

Only enrich logs when running on AWS:

builder.Host.UseSerilog((context, services, configuration) =>
{
    var loggerConfig = configuration.ReadFrom.Configuration(context.Configuration);
    
    if (EC2MetadataConfigurationProvider.IsRunningOnBeanstalk())
    {
        loggerConfig.Enrich.WithElasticBeanstalk(services);
    }
    
    loggerConfig.WriteTo.Console();
});

Integration with Other Enrichers

Combine with other Serilog enrichers:

builder.Host.UseSerilog((context, services, configuration) =>
{
    configuration
        .ReadFrom.Configuration(context.Configuration)
        .Enrich.FromLogContext()
        .Enrich.WithMachineName()
        .Enrich.WithProcessId()
        .Enrich.WithThreadId()
        .Enrich.WithElasticBeanstalk(services)  // AWS Beanstalk enrichment
        .WriteTo.Console()
        .WriteTo.Elasticsearch("http://localhost:9200");
});

📊 Log Analysis Benefits

With AWS Beanstalk enrichment, you can easily:

Query Logs by Environment

level:Error AND aws.beanstalk.EnvironmentName:production

Filter by Application Version

aws.beanstalk.VersionLabel:v1.2.3 AND level:Warning

Monitor Specific Instances

aws.beanstalk.InstanceId:i-1234567890abcdef0

Track Deployments

aws.beanstalk.ApplicationName:my-app AND aws.beanstalk.DateUpdated:>2023-01-20

🔧 Service Registration Details

The AddAmazonSerilogEnrichment() extension method registers:

public static IServiceCollection AddAmazonSerilogEnrichment(
    this IServiceCollection services, 
    IConfiguration configuration)
{
    // Registers EnvironmentDetails from configuration
    services.AddBeanstalkEnvironmentDetails(configuration);
    
    // Registers the Serilog enricher
    services.AddSingleton<ElasticBeanstalkEnricher>();
    
    return services;
}

🚦 Build Status

Branch	Status	Version
Main
Develop

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

Development Setup

1. Clone the repository
2. Ensure you have .NET 8+ SDK installed
3. Run dotnet restore in the src directory
4. Build with dotnet build
5. Run tests with dotnet test

Running Tests Locally

export elasticbeanstalk_environment_islocal=true
dotnet test

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙋‍♂️ Support

If you encounter any issues or have questions:

1. Check the Issues page
2. Create a new issue with detailed information
3. For urgent matters, contact the maintainers

🔗 Related Projects

• Sustainment.Extensions.Configuration.Amazon - AWS EC2 Metadata Configuration Provider
• Serilog - Structured logging for .NET
• AWS SDK for .NET

⭐ If this project helped you, please consider giving it a star!