diff --git a/OpenTelemetry.sln b/OpenTelemetry.sln index 922ba6b2d20..efff1dbed0f 100644 --- a/OpenTelemetry.sln +++ b/OpenTelemetry.sln @@ -90,8 +90,8 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "ISSUE_TEMPLATE", "ISSUE_TEM EndProject Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "workflows", "workflows", "{E69578EB-B456-4062-A645-877CD964528B}" ProjectSection(SolutionItems) = preProject - .github\workflows\ci-aot.yml = .github\workflows\ci-aot.yml .github\workflows\ci-aot-md.yml = .github\workflows\ci-aot-md.yml + .github\workflows\ci-aot.yml = .github\workflows\ci-aot.yml .github\workflows\ci-instrumentation-libraries-md.yml = .github\workflows\ci-instrumentation-libraries-md.yml .github\workflows\ci-instrumentation-libraries.yml = .github\workflows\ci-instrumentation-libraries.yml .github\workflows\ci-md.yml = .github\workflows\ci-md.yml @@ -315,6 +315,8 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Metrics", "Metrics", "{1C45 EndProject Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "getting-started-aspnetcore", "docs\logs\getting-started-aspnetcore\getting-started-aspnetcore.csproj", "{99B4D965-8782-4694-8DFA-B7A3630CEF60}" EndProject +Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "links-creation", "docs\trace\links-creation-with-new-activities\links-creation.csproj", "{B4856711-6D4C-4246-A686-49458D4C1301}" +EndProject Global GlobalSection(SolutionConfigurationPlatforms) = preSolution Debug|Any CPU = Debug|Any CPU @@ -589,6 +591,10 @@ Global {99B4D965-8782-4694-8DFA-B7A3630CEF60}.Debug|Any CPU.Build.0 = Debug|Any CPU {99B4D965-8782-4694-8DFA-B7A3630CEF60}.Release|Any CPU.ActiveCfg = Release|Any CPU {99B4D965-8782-4694-8DFA-B7A3630CEF60}.Release|Any CPU.Build.0 = Release|Any CPU + {B4856711-6D4C-4246-A686-49458D4C1301}.Debug|Any CPU.ActiveCfg = Debug|Any CPU + {B4856711-6D4C-4246-A686-49458D4C1301}.Debug|Any CPU.Build.0 = Debug|Any CPU + {B4856711-6D4C-4246-A686-49458D4C1301}.Release|Any CPU.ActiveCfg = Release|Any CPU + {B4856711-6D4C-4246-A686-49458D4C1301}.Release|Any CPU.Build.0 = Release|Any CPU EndGlobalSection GlobalSection(SolutionProperties) = preSolution HideSolutionNode = FALSE @@ -637,6 +643,7 @@ Global {A0CB9A10-F22D-4E66-A449-74B3D0361A9C} = {A49299FB-C5CD-4E0E-B7E1-B7867BBD67CC} {1C459B5B-C702-46FF-BF1A-EE795E420FFA} = {A49299FB-C5CD-4E0E-B7E1-B7867BBD67CC} {99B4D965-8782-4694-8DFA-B7A3630CEF60} = {3862190B-E2C5-418E-AFDC-DB281FB5C705} + {B4856711-6D4C-4246-A686-49458D4C1301} = {5B7FB835-3FFF-4BC2-99C5-A5B5FAE3C818} EndGlobalSection GlobalSection(ExtensibilityGlobals) = postSolution SolutionGuid = {55639B5C-0770-4A22-AB56-859604650521} diff --git a/docs/trace/links-creation-with-new-activities/Program.cs b/docs/trace/links-creation-with-new-activities/Program.cs new file mode 100644 index 00000000000..d762db4ff9c --- /dev/null +++ b/docs/trace/links-creation-with-new-activities/Program.cs @@ -0,0 +1,81 @@ +// +// Copyright The OpenTelemetry Authors +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +// + +using System.Diagnostics; +using OpenTelemetry; +using OpenTelemetry.Trace; + +namespace LinksCreationWithNewRootActivitiesDemo; + +internal class Program +{ + private static readonly ActivitySource MyActivitySource = new("LinksCreationWithNewRootActivities"); + + public static void Main(string[] args) + { + using var tracerProvider = Sdk.CreateTracerProviderBuilder() + .AddSource("LinksCreationWithNewRootActivities") + .AddConsoleExporter() + .Build(); + + using (var activity = MyActivitySource.StartActivity("SayHello")) + { + activity?.SetTag("foo", 1); + DoFanout(); + + using (var nestedActivity = MyActivitySource.StartActivity("WrapUp")) + { + nestedActivity?.SetTag("foo", 1); + } + } + } + + public static void DoFanout() + { + var previous = Activity.Current; + + var activityContext = Activity.Current!.Context; + var links = new List + { + new ActivityLink(activityContext), + }; + + // Fanning out to 10 different operations. + // We create a new root activity for each operation and + // link it to an outer activity that happens to be the current + // activity. + for (int i = 0; i < 10; i++) + { + // Reference: https://opentelemetry.io/docs/instrumentation/net/manual/#creating-new-root-activities + // Since we want to create a new root activity for each of the fanned out operations, + // this step helps us "de-parent" it from the current activity. + Activity.Current = null; + + // Reference: https://opentelemetry.io/docs/instrumentation/net/manual/#adding-links + // We create a new root activity for each of the fanned out operations and link it to the outer activity. + using var newRootActivityForFannedOutOperation = MyActivitySource.StartActivity( + ActivityKind.Internal, // Set this to the appropriate ActivityKind depending on your scenario + name: "FannedOutActivity", + links: links); + + // DO THE FANOUT WORK HERE... + } + + // Reset to the previous activity now that we are done with the fanout + // This will ensure that the rest of the code executes in the context of that activity. + Activity.Current = previous; + } +} diff --git a/docs/trace/links-creation-with-new-activities/README.md b/docs/trace/links-creation-with-new-activities/README.md new file mode 100644 index 00000000000..24245050262 --- /dev/null +++ b/docs/trace/links-creation-with-new-activities/README.md @@ -0,0 +1,118 @@ +# Creating new root activities that link to an existing activity: An Example + +This example shows how to create new root activities that link to an existing +activity. This can be useful in a fan-out or batched operation situation when +you want to create a new trace with a new root activity before invoking each +of the fanned out operations. + +This example shows to create the new root activities and link each of them to +the original activity. + +## How does this example work? + +To be able to create new root activities, we first set the Activity.Current +to null so that we can "de-parent" the new activity from the current activity. + +For each of the fanned out operations, this creates a new root activity. As +part of this activity creation, it links it to the previously current activity. + +Finally, we reset Activity.Current to the previous activity now after we are +done with the fanout. This will ensure that the rest of the code executes +in the context of the original activity. + +## When should you consider such an option? What are the tradeoffs? + +This is a good option to consider for operations that involve several batched +or fanout operations. Using this approach, you can create a new trace for each +of the fanned out operations and link them to the original activity. + +## References +- https://opentelemetry.io/docs/instrumentation/net/manual/#creating-new-root-activities +- https://opentelemetry.io/docs/instrumentation/net/manual/#adding-links + +## Sample Output + +You should see output such as the below when you run this example. + +```text +Activity.TraceId: 5ce4d8ad4926ecdd0084681f46fa38d9 +Activity.SpanId: 8f9e9441f0789f6e +Activity.TraceFlags: Recorded +Activity.ActivitySourceName: LinksCreationWithNewRootActivities +Activity.DisplayName: FannedOutActivity +Activity.Kind: Internal +Activity.StartTime: 2023-10-17T01:24:40.4957326Z +Activity.Duration: 00:00:00.0008656 +Activity.Links: + 2890476acefb53b93af64a0d91939051 16b83c1517629363 +Resource associated with Activity: + telemetry.sdk.name: opentelemetry + telemetry.sdk.language: dotnet + telemetry.sdk.version: 0.0.0-alpha.0.2600 + service.name: unknown_service:links-creation + +Activity.TraceId: 16a8ad23d14a085f2a1f260a4b474d05 +Activity.SpanId: 0c3e835cfd60c604 +Activity.TraceFlags: Recorded +Activity.ActivitySourceName: LinksCreationWithNewRootActivities +Activity.DisplayName: FannedOutActivity +Activity.Kind: Internal +Activity.StartTime: 2023-10-17T01:24:40.5908290Z +Activity.Duration: 00:00:00.0009197 +Activity.Links: + 2890476acefb53b93af64a0d91939051 16b83c1517629363 +Resource associated with Activity: + telemetry.sdk.name: opentelemetry + telemetry.sdk.language: dotnet + telemetry.sdk.version: 0.0.0-alpha.0.2600 + service.name: unknown_service:links-creation + +Activity.TraceId: 46f0b5b68173b4acf4f50e1f5cdb3e55 +Activity.SpanId: 42e7f4439fc2b416 +Activity.TraceFlags: Recorded +Activity.ActivitySourceName: LinksCreationWithNewRootActivities +Activity.DisplayName: FannedOutActivity +Activity.Kind: Internal +Activity.StartTime: 2023-10-17T01:24:40.5930378Z +Activity.Duration: 00:00:00.0008622 +Activity.Links: + 2890476acefb53b93af64a0d91939051 16b83c1517629363 +Resource associated with Activity: + telemetry.sdk.name: opentelemetry + telemetry.sdk.language: dotnet + telemetry.sdk.version: 0.0.0-alpha.0.2600 + service.name: unknown_service:links-creation + +Activity.TraceId: 2890476acefb53b93af64a0d91939051 +Activity.SpanId: 6878c2a84d4d4996 +Activity.TraceFlags: Recorded +Activity.ParentSpanId: 16b83c1517629363 +Activity.ActivitySourceName: LinksCreationWithNewRootActivities +Activity.DisplayName: WrapUp +Activity.Kind: Internal +Activity.StartTime: 2023-10-17T01:24:40.5950683Z +Activity.Duration: 00:00:00.0008843 +Activity.Tags: + foo: 1 +Resource associated with Activity: + telemetry.sdk.name: opentelemetry + telemetry.sdk.language: dotnet + telemetry.sdk.version: 0.0.0-alpha.0.2600 + service.name: unknown_service:links-creation + +Activity.TraceId: 2890476acefb53b93af64a0d91939051 +Activity.SpanId: 16b83c1517629363 +Activity.TraceFlags: Recorded +Activity.ActivitySourceName: LinksCreationWithNewRootActivities +Activity.DisplayName: SayHello +Activity.Kind: Internal +Activity.StartTime: 2023-10-17T01:24:40.4937024Z +Activity.Duration: 00:00:00.1043390 +Activity.Tags: + foo: 1 +Resource associated with Activity: + telemetry.sdk.name: opentelemetry + telemetry.sdk.language: dotnet + telemetry.sdk.version: 0.0.0-alpha.0.2600 + service.name: unknown_service:links-creation +``` diff --git a/docs/trace/links-creation-with-new-activities/links-creation.csproj b/docs/trace/links-creation-with-new-activities/links-creation.csproj new file mode 100644 index 00000000000..19aa9791432 --- /dev/null +++ b/docs/trace/links-creation-with-new-activities/links-creation.csproj @@ -0,0 +1,5 @@ + + + + +