Skip to content

Commit df56b11

Browse files
DPschichholzDPschichholz
authored
Add OpenTelemetry instrumentation project and update README (#102)
* Add OpenTelemetry instrumentation project and update README * Rename OpenTelemetry.Instrumentation.PhenX.EntityFrameworkCore.BulkInsert -> PhenX.EntityFrameworkCore.BulkInsert.OpenTelemetry * Format Tables
1 parent 03e3619 commit df56b11

6 files changed

Lines changed: 129 additions & 8 deletions

File tree

‎PhenX.EntityFrameworkCore.BulkInsert.slnx‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@
99
<Folder Name="/src/">
1010
<File Path="src/Directory.Build.props" />
1111
<Project Path="src/PhenX.EntityFrameworkCore.BulkInsert.MySql/PhenX.EntityFrameworkCore.BulkInsert.MySql.csproj" />
12+
<Project Path="src/PhenX.EntityFrameworkCore.BulkInsert.OpenTelemetry/PhenX.EntityFrameworkCore.BulkInsert.OpenTelemetry.csproj" />
1213
<Project Path="src/PhenX.EntityFrameworkCore.BulkInsert.Oracle/PhenX.EntityFrameworkCore.BulkInsert.Oracle.csproj" />
1314
<Project Path="src/PhenX.EntityFrameworkCore.BulkInsert.PostgreSql/PhenX.EntityFrameworkCore.BulkInsert.PostgreSql.csproj" />
1415
<Project Path="src/PhenX.EntityFrameworkCore.BulkInsert.Sqlite/PhenX.EntityFrameworkCore.BulkInsert.Sqlite.csproj" />

‎README.md‎

Lines changed: 12 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -15,14 +15,15 @@ but they are in [the roadmap](#roadmap).
1515

1616
## Packages
1717

18-
| Package Name | Description | NuGet Link |
19-
|---------------------------------------------------|----------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
20-
| `PhenX.EntityFrameworkCore.BulkInsert.SqlServer` | For SQL Server | [![NuGet](https://img.shields.io/nuget/v/PhenX.EntityFrameworkCore.BulkInsert.SqlServer.svg)](https://www.nuget.org/packages/PhenX.EntityFrameworkCore.BulkInsert.SqlServer) |
21-
| `PhenX.EntityFrameworkCore.BulkInsert.PostgreSql` | For PostgreSQL | [![NuGet](https://img.shields.io/nuget/v/PhenX.EntityFrameworkCore.BulkInsert.PostgreSql.svg)](https://www.nuget.org/packages/PhenX.EntityFrameworkCore.BulkInsert.PostgreSql) |
22-
| `PhenX.EntityFrameworkCore.BulkInsert.Sqlite` | For SQLite | [![NuGet](https://img.shields.io/nuget/v/PhenX.EntityFrameworkCore.BulkInsert.Sqlite.svg)](https://www.nuget.org/packages/PhenX.EntityFrameworkCore.BulkInsert.Sqlite) |
23-
| `PhenX.EntityFrameworkCore.BulkInsert.MySql` | For MySql | [![NuGet](https://img.shields.io/nuget/v/PhenX.EntityFrameworkCore.BulkInsert.Sqlite.svg)](https://www.nuget.org/packages/PhenX.EntityFrameworkCore.BulkInsert.MySql) |
24-
| `PhenX.EntityFrameworkCore.BulkInsert.Oracle` | For Oracle | [![NuGet](https://img.shields.io/nuget/v/PhenX.EntityFrameworkCore.BulkInsert.Oracle.svg)](https://www.nuget.org/packages/PhenX.EntityFrameworkCore.BulkInsert.Oracle) |
25-
| `PhenX.EntityFrameworkCore.BulkInsert` | Common library | [![NuGet](https://img.shields.io/nuget/v/PhenX.EntityFrameworkCore.BulkInsert.svg)](https://www.nuget.org/packages/PhenX.EntityFrameworkCore.BulkInsert) |
18+
| Package Name | Description | NuGet Link |
19+
|------------------------------------------------------|-------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
20+
| `PhenX.EntityFrameworkCore.BulkInsert.SqlServer` | For SQL Server | [![NuGet](https://img.shields.io/nuget/v/PhenX.EntityFrameworkCore.BulkInsert.SqlServer.svg)](https://www.nuget.org/packages/PhenX.EntityFrameworkCore.BulkInsert.SqlServer) |
21+
| `PhenX.EntityFrameworkCore.BulkInsert.PostgreSql` | For PostgreSQL | [![NuGet](https://img.shields.io/nuget/v/PhenX.EntityFrameworkCore.BulkInsert.PostgreSql.svg)](https://www.nuget.org/packages/PhenX.EntityFrameworkCore.BulkInsert.PostgreSql) |
22+
| `PhenX.EntityFrameworkCore.BulkInsert.Sqlite` | For SQLite | [![NuGet](https://img.shields.io/nuget/v/PhenX.EntityFrameworkCore.BulkInsert.Sqlite.svg)](https://www.nuget.org/packages/PhenX.EntityFrameworkCore.BulkInsert.Sqlite) |
23+
| `PhenX.EntityFrameworkCore.BulkInsert.MySql` | For MySql | [![NuGet](https://img.shields.io/nuget/v/PhenX.EntityFrameworkCore.BulkInsert.Sqlite.svg)](https://www.nuget.org/packages/PhenX.EntityFrameworkCore.BulkInsert.MySql) |
24+
| `PhenX.EntityFrameworkCore.BulkInsert.Oracle` | For Oracle | [![NuGet](https://img.shields.io/nuget/v/PhenX.EntityFrameworkCore.BulkInsert.Oracle.svg)](https://www.nuget.org/packages/PhenX.EntityFrameworkCore.BulkInsert.Oracle) |
25+
| `PhenX.EntityFrameworkCore.BulkInsert` | Common library | [![NuGet](https://img.shields.io/nuget/v/PhenX.EntityFrameworkCore.BulkInsert.svg)](https://www.nuget.org/packages/PhenX.EntityFrameworkCore.BulkInsert) |
26+
| `PhenX.EntityFrameworkCore.BulkInsert.OpenTelemetry` | OpenTelemetry instrumentation | [![NuGet](https://img.shields.io/nuget/v/PhenX.EntityFrameworkCore.BulkInsert.svg)](https://www.nuget.org/packages/PhenX.EntityFrameworkCore.BulkInsert.OpenTelemetry) |
2627

2728
### Dependencies
2829

@@ -51,6 +52,9 @@ Install-Package PhenX.EntityFrameworkCore.BulkInsert.MySql
5152

5253
# For Oracle
5354
Install-Package PhenX.EntityFrameworkCore.BulkInsert.Oracle
55+
56+
# For OpenTelemetry instrumentation
57+
Install-Package PhenX.EntityFrameworkCore.BulkInsert.OpenTelemetry
5458
```
5559

5660
## Usage

‎docs/.vitepress/config.mts‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -48,6 +48,12 @@ export default defineConfig({
4848
{
4949
text: 'Documentation',
5050
link: '/documentation',
51+
items: [
52+
{
53+
text: 'OpenTelemetry',
54+
link: '/opentelemetry',
55+
},
56+
],
5157
},
5258
{
5359
text: 'Limitations',

‎docs/opentelemetry.md‎

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
---
2+
title: OpenTelemetry Instrumentation
3+
lang: en-US
4+
---
5+
6+
# OpenTelemetry Instrumentation
7+
8+
PhenX.EntityFrameworkCore.BulkInsert has built-in support for [OpenTelemetry](https://opentelemetry.io/) tracing via the `PhenX.EntityFrameworkCore.BulkInsert.OpenTelemetry` package.
9+
10+
Each bulk insert operation is automatically tracked as an [Activity](https://learn.microsoft.com/en-us/dotnet/api/system.diagnostics.activity) using the `PhenX.EntityFrameworkCore.BulkInsert` activity source, enabling distributed tracing and performance monitoring in your application.
11+
12+
## Installation
13+
14+
Install the instrumentation NuGet package:
15+
16+
```shell
17+
Install-Package PhenX.EntityFrameworkCore.BulkInsert.OpenTelemetry
18+
```
19+
20+
## Configuration
21+
22+
Register the instrumentation when configuring your OpenTelemetry `TracerProvider` by calling `AddPhenXEntityFrameworkCoreBulkInsertInstrumentation()`:
23+
24+
```csharp
25+
using OpenTelemetry.Trace;
26+
27+
builder.Services.AddOpenTelemetry()
28+
.WithTracing(tracing => tracing
29+
.AddAspNetCoreInstrumentation()
30+
.AddPhenXEntityFrameworkCoreBulkInsertInstrumentation() // <-- add this
31+
.AddOtlpExporter()
32+
);
33+
```
34+
35+
## `TracerProviderBuilderExtensions`
36+
37+
### `AddPhenXEntityFrameworkCoreBulkInsertInstrumentation`
38+
39+
```csharp
40+
public static TracerProviderBuilder AddPhenXEntityFrameworkCoreBulkInsertInstrumentation(
41+
this TracerProviderBuilder builder)
42+
```
43+
44+
Adds the `PhenX.EntityFrameworkCore.BulkInsert` activity source to the given `TracerProviderBuilder`.
45+
46+
**Parameters**
47+
48+
| Parameter | Type | Description |
49+
|-----------|-------------------------|------------------------------------------------------------|
50+
| `builder` | `TracerProviderBuilder` | The `TracerProviderBuilder` to add the instrumentation to. |
51+
52+
**Returns**
53+
54+
The `TracerProviderBuilder` with the `PhenX.EntityFrameworkCore.BulkInsert` instrumentation registered.
55+
56+
## Traced Operations
57+
58+
The following bulk insert operations produce OpenTelemetry traces:
59+
60+
| Operation | Description |
61+
|----------------------------------------|------------------------------------------------|
62+
| `ExecuteBulkInsert` | Synchronous bulk insert without entity return |
63+
| `ExecuteBulkInsertAsync` | Asynchronous bulk insert without entity return |
64+
| `ExecuteBulkInsertReturnEntities` | Synchronous bulk insert with entity return |
65+
| `ExecuteBulkInsertReturnEntitiesAsync` | Asynchronous bulk insert with entity return |
66+
67+
## Activity Source
68+
69+
The activity source name used by this library is:
70+
71+
```
72+
PhenX.EntityFrameworkCore.BulkInsert
73+
```
74+
75+
You can use this name to subscribe directly to the activity source if you need lower-level access:
76+
77+
```csharp
78+
using System.Diagnostics;
79+
80+
ActivitySource.AddActivityListener(new ActivityListener
81+
{
82+
ShouldListenTo = source => source.Name == "PhenX.EntityFrameworkCore.BulkInsert",
83+
Sample = (ref ActivityCreationOptions<ActivityContext> _) => ActivitySamplingResult.AllDataAndRecorded,
84+
ActivityStarted = activity => Console.WriteLine($"Started: {activity.DisplayName}"),
85+
ActivityStopped = activity => Console.WriteLine($"Stopped: {activity.DisplayName} ({activity.Duration})"),
86+
});
87+
```

‎src/PhenX.EntityFrameworkCore.BulkInsert.OpenTelemetry/PhenX.EntityFrameworkCore.BulkInsert.OpenTelemetry.csproj‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
<Project Sdk="Microsoft.NET.Sdk">
2+
<ItemGroup>
3+
<PackageReference Include="OpenTelemetry.Api" Version="1.*" />
4+
</ItemGroup>
5+
</Project>

‎src/PhenX.EntityFrameworkCore.BulkInsert.OpenTelemetry/TracerProviderBuilderExtensions.cs‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
using OpenTelemetry.Trace;
2+
namespace PhenX.EntityFrameworkCore.BulkInsert.OpenTelemetry;
3+
4+
/// <summary>
5+
/// Extension methods for <see cref="TracerProviderBuilder"/> to add instrumentation for PhenX.EntityFrameworkCore.BulkInsert.
6+
/// </summary>
7+
public static class TracerProviderBuilderExtensions
8+
{
9+
/// <summary>
10+
/// Adds instrumentation for PhenX.EntityFrameworkCore.BulkInsert to the OpenTelemetry TracerProviderBuilder.
11+
/// </summary>
12+
/// <param name="builder">The TracerProviderBuilder to add the instrumentation to.</param>
13+
/// <returns>The TracerProviderBuilder with the PhenX.EntityFrameworkCore.BulkInsert instrumentation added.</returns>
14+
public static TracerProviderBuilder AddPhenXEntityFrameworkCoreBulkInsertInstrumentation(this TracerProviderBuilder builder)
15+
{
16+
return builder.AddSource("PhenX.EntityFrameworkCore.BulkInsert");
17+
}
18+
}

0 commit comments

Comments
 (0)