Skip to content

Latest commit

 

History

History
267 lines (191 loc) · 8.84 KB

README.md

File metadata and controls

267 lines (191 loc) · 8.84 KB
Raw


NuGet

Epsagon Tracing for .NET

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

Contents

Installation

To install Epsagon, simply run:

dotnet add package Epsagon.Dotnet.Lambda

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

Usage

Trace URL

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.

Frameworks

The following frameworks are supported by Epsagon:

Framework Supported Version
ASP.NET MVC >=2.1
AWS Lambda All
Generic Function All

AWS Lambda

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.

To Inherit from Epsagon's LambdaHandler Base Class (example for S3 trigger)

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.

Passing a callback

  • 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
        });
    }
}

ASP.NET MVC

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).

Generic Function

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).

Adding Labels

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!

Integrations

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

Library Supported Version
Elasticsearch >=5.6
MongoDB.Driver >=2.4
AWSSDK >=3.0
ASP.NET MVC >=2.1
ADO.NET all
EFCore >=2.1.0
StackExchange.Redis >=2

Elasticsearch

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);

MongoDB

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

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

ADO.NET

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

EFCore integration is done automatically, no need for extra actions

StackExchange.Redis

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

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

Configuration

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

Parameter Environment Variable Type Default Description
Token EPSAGON_TOKEN String - Epsagon account token
ApplicationName EPSAGON_APP_NAME String - Application name that will be set for traces
MetadataOnly EPSAGON_METADATA Boolean true Whether to send only the metadata (true) or also the payloads (false)
TraceCollectorURL - String - The address of the trace collector to send trace to
UseSSL Boolean true Whether to send the traces over HTTPS SSL or not
IsEpsagonDisabled DISABLE_EPSAGON Boolean false A flag to completely disable Epsagon (can be used for tests or locally)
_ EPSAGON_DEBUG Boolean false Enable debug prints for troubleshooting
LogFile EPSAGON_LOG_FILE String - Enable logging to the specified file path

Getting Help

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.

Opening Issues

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.

License

Provided under the MIT license. See LICENSE for details.

Copyright 2020, Epsagon