Note: This repository is archived since Epsagon is no longer supported

This package provides tracing to .NET applications for the collection of distributed tracing and performance metrics in Epsagon.

• Installation
• Usage
  • Trace URL
• Frameworks
• Integrations
• Configuration
• Getting Help
• Opening Issues
• License

To install Epsagon, simply run:

dotnet add package Epsagon.Dotnet.Lambda

Or, using PackageReference in a *.csproj file, follow instructions here.

You can get the Epsagon dashboard URL for the current trace, using the following:

# Inside some endpoint or function
Console.WriteLine("Epsagon trace URL: "+ EpsagonUtils.GetTraceUrl())

This can be useful to have an easy access the trace from different platforms.

The following frameworks are supported by Epsagon:

Tracing Lambda functions can be done in three methods:

1. Inherit from Epsagon's LambdaHandler Base Class.
2. Passing a callback.

• Set the following environment variables:
  • EPSAGON_TOKEN - Epsagon's token, can be found in the Dashboard.
  • EPSAGON_APP_NAME - Name for the application of this function (optional).
• Generate a new AWS Lambda Function project (For more info).
• Add Epsagon.Dotnet.Lambda package to your project.

public class Function : LambdaHandler<S3Event, string> // LambdaHandler<TEvent, TRes>
{
    public override async Task<string> HandlerFunction(S3Event input, ILambdaContext context)
    {
        return "Hello from Epsagon!";
    }
}

Change the function-handler in your project's aws-lambda-tools-defaults.json to be EpsagonEnabledHandler.

• Add a call to EpsagonBootstrap.Bootstrap() in the constructor of your Lambda.
• Invoke EpsagonHandler.Handle to instrument your function.

public class FunctionClass {
    public FunctionClass() {
        EpsagonBootstrap.Bootstrap();
    }

    public string MyHandler(S3Event input, ILambdaContext context) {
        return EpsagonHandler.Handle(input, context, () => {
            // your code is here...
        });
    }

    // Can be async as well
    public Task<string> MyAsyncHandler(S3Event input, ILambdaContext context) {
        return EpsagonHandler.Handle(input, context, async () => {
            // your async code is here
        });
    }
}

To trace ASP.NET MVC, a few simple actions should be taken:

• Add Epsagon.Dotnet.Mvc package to your project.
• Add a call to EpsagonBootstrap.Bootstrap() in the constructor of your startup class. for example:

public Startup(IConfiguration configuration)
{
    EpsagonBootstrap.Bootstrap();
    Configuration = configuration;
}

• Add EpsagonMiddleware to your MVC project. for example:

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    app.UseEpsagon();
}

• Set the following environment variables:
  • EPSAGON_TOKEN - Epsagon's token, can be found in the Dashboard.
  • EPSAGON_APP_NAME - Name for the application of this function (optional).

To trace any generic function, only a single step is needed:

1. Use EpsagonGeneralHandler to wrap your code, see snippet below

public string FunctionToWrap(string param)
{
    return EpsagonGeneralHandler.Handle(() =>
    {
      // ...
      return param;
    });
}

• Set the following environment variables:
  • EPSAGON_TOKEN - Epsagon's token, can be found in the Dashboard.
  • EPSAGON_APP_NAME - Name for the application of this function (optional).

To enrich your trace with additional information you can use the EpsagonLabels class:

// ...
EpsagonLabels.Add("some-key", "some-value");

each label is displayed on the trace view in Epsagon's Dashboard and is automatically searchable!

Epsagon provides out-of-the-box instrumentation (tracing) for many popular frameworks and libraries.

To enable Epsagon's Elasticsearch integration call the UseEpsagon() method when creating a connection:

var settings = new ConnectionSettings()
    .DefaultIndex("some-index")
    ...
    .UseEpsagon();
var client = new ElasticClient(settings);

To enable Epsagon's MongoDB integration call the WithEpsagon() method when creating a connection:

var client = new MongoClient("mongodb://localhost:27017").WithEpsagon();

To enable Epsagon's ADO.NET integration call the UseEpsagon() method on the SqlConnection object:

// can be any ADO.NET sql connection object (SQLiteConnection / NpgsqlConnection / etc.)
var connection = new SomeSqlConnection("connection-string").UseEpsagon();

EFCore integration is done automatically, no need for extra actions

To enable Epsagon's StackExchange.Redis integration call the UseEpsagon() method on the connection object:

var connection = ConnectionMultiplexer.Connect("localhost").UseEpsagon();

Advanced options can be configured as a parameter to the Config struct to the WrapLambdaHandler or as environment variables.

If you have any issue around using the library or the product, please don't hesitate to:

• Use the documentation.
• Use the help widget inside the product.
• Open an issue in GitHub.

If you encounter a bug with the Epsagon library for .NET, we want to hear about it.

When opening a new issue, please provide as much information about the environment:

• Library version, .NET runtime version, dependencies, etc.
• Snippet of the usage.
• A reproducible example can really help.

The GitHub issues are intended for bug reports and feature requests. For help and questions about Epsagon, use the help widget inside the product.

Provided under the MIT license. See LICENSE for details.

Copyright 2020, Epsagon