Skip to content

Commit 62ab16f

Browse files
hjgracahjgraca
committed
docs(metrics): extract inline code examples into snippet files
Extract 30 inline C# code blocks from docs/core/metrics.md into standalone snippet files under docs/snippets/metrics/ using pymdownx.snippets includes. Fix mislabeled python code block. No visual changes to rendered documentation. Closes #1187
1 parent c643bbc commit 62ab16f

10 files changed

Lines changed: 677 additions & 526 deletions

‎docs/core/metrics.md‎

Lines changed: 34 additions & 526 deletions
Large diffs are not rendered by default.

‎docs/snippets/metrics/AddingDimensions.cs‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
// This file is referenced by docs/core/metrics.md
2+
// via pymdownx.snippets (mkdocs).
3+
4+
namespace AWS.Lambda.Powertools.Docs.Snippets.Metrics;
5+
6+
// --8<-- [start:adding_dimensions]
7+
using AWS.Lambda.Powertools.Metrics;
8+
9+
public class Function {
10+
11+
[Metrics(Namespace = "ExampleApplication", Service = "Booking")]
12+
public async Task<APIGatewayProxyResponse> FunctionHandler(APIGatewayProxyRequest apigProxyEvent, ILambdaContext context)
13+
{
14+
Metrics.AddDimension("Environment","Prod");
15+
Metrics.AddMetric("SuccessfulBooking", 1, MetricUnit.Count);
16+
}
17+
}
18+
// --8<-- [end:adding_dimensions]

‎docs/snippets/metrics/AdvancedConfiguration.cs‎

Lines changed: 131 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,131 @@
1+
// This file is referenced by docs/core/metrics.md
2+
// via pymdownx.snippets (mkdocs).
3+
4+
namespace AWS.Lambda.Powertools.Docs.Snippets.Metrics;
5+
6+
// --8<-- [start:adding_metadata]
7+
using AWS.Lambda.Powertools.Metrics;
8+
9+
public class Function {
10+
11+
[Metrics(Namespace = ExampleApplication, Service = "Booking")]
12+
public async Task<APIGatewayProxyResponse> FunctionHandler(APIGatewayProxyRequest apigProxyEvent, ILambdaContext context)
13+
{
14+
Metrics.AddMetric("SuccessfulBooking", 1, MetricUnit.Count);
15+
Metrics.AddMetadata("BookingId", "683EEB2D-B2F3-4075-96EE-788E6E2EED45");
16+
...
17+
// --8<-- [end:adding_metadata]
18+
19+
// --8<-- [start:push_single_metric]
20+
using AWS.Lambda.Powertools.Metrics;
21+
22+
public class Function {
23+
24+
[Metrics(Namespace = ExampleApplication, Service = "Booking")]
25+
public async Task<APIGatewayProxyResponse> FunctionHandler(APIGatewayProxyRequest apigProxyEvent, ILambdaContext context)
26+
{
27+
Metrics.PushSingleMetric(
28+
name: "ColdStart",
29+
value: 1,
30+
unit: MetricUnit.Count,
31+
nameSpace: "ExampleApplication",
32+
service: "Booking");
33+
...
34+
// --8<-- [end:push_single_metric]
35+
36+
// --8<-- [start:single_metric_new_dimensions]
37+
using AWS.Lambda.Powertools.Metrics;
38+
39+
public class Function {
40+
41+
[Metrics(Namespace = ExampleApplication, Service = "Booking")]
42+
public async Task<APIGatewayProxyResponse> FunctionHandler(APIGatewayProxyRequest apigProxyEvent, ILambdaContext context)
43+
{
44+
Metrics.PushSingleMetric(
45+
name: "ColdStart",
46+
value: 1,
47+
unit: MetricUnit.Count,
48+
nameSpace: "ExampleApplication",
49+
service: "Booking",
50+
dimensions: new Dictionary<string, string>
51+
{
52+
{"FunctionContext", "$LATEST"}
53+
});
54+
...
55+
// --8<-- [end:single_metric_new_dimensions]
56+
57+
// --8<-- [start:single_metric_default_dimensions_static]
58+
using AWS.Lambda.Powertools.Metrics;
59+
60+
public class Function {
61+
62+
[Metrics(Namespace = ExampleApplication, Service = "Booking")]
63+
public async Task<APIGatewayProxyResponse> FunctionHandler(APIGatewayProxyRequest apigProxyEvent, ILambdaContext context)
64+
{
65+
Metrics.SetDefaultDimensions(new Dictionary<string, string>
66+
{
67+
{ "Default", "SingleMetric" }
68+
});
69+
Metrics.PushSingleMetric("SingleMetric", 1, MetricUnit.Count, dimensions: Metrics.DefaultDimensions );
70+
...
71+
// --8<-- [end:single_metric_default_dimensions_static]
72+
73+
// --8<-- [start:single_metric_default_dimensions_options]
74+
using AWS.Lambda.Powertools.Metrics;
75+
76+
public MetricsnBuilderHandler(IMetrics metrics = null)
77+
{
78+
_metrics = metrics ?? new MetricsBuilder()
79+
.WithCaptureColdStart(true)
80+
.WithService("testService")
81+
.WithNamespace("dotnet-powertools-test")
82+
.WithDefaultDimensions(new Dictionary<string, string>
83+
{
84+
{ "Environment", "Prod1" },
85+
{ "Another", "One" }
86+
}).Build();
87+
}
88+
89+
public void HandlerSingleMetricDimensions()
90+
{
91+
_metrics.PushSingleMetric("SuccessfulBooking", 1, MetricUnit.Count, dimensions: _metrics.Options.DefaultDimensions);
92+
}
93+
...
94+
// --8<-- [end:single_metric_default_dimensions_options]
95+
96+
// --8<-- [start:function_name_decorator]
97+
using AWS.Lambda.Powertools.Metrics;
98+
99+
public class Function {
100+
101+
[Metrics(FunctionName = "MyFunctionName", Namespace = "ExampleApplication", Service = "Booking")]
102+
public async Task<APIGatewayProxyResponse> FunctionHandler(APIGatewayProxyRequest apigProxyEvent, ILambdaContext context)
103+
{
104+
Metrics.AddMetric("SuccessfulBooking", 1, MetricUnit.Count);
105+
...
106+
}
107+
// --8<-- [end:function_name_decorator]
108+
109+
// --8<-- [start:function_name_configure]
110+
using AWS.Lambda.Powertools.Metrics;
111+
112+
public class Function {
113+
114+
public Function()
115+
{
116+
Metrics.Configure(options =>
117+
{
118+
options.Namespace = "dotnet-powertools-test";
119+
options.Service = "testService";
120+
options.CaptureColdStart = true;
121+
options.FunctionName = "MyFunctionName";
122+
});
123+
}
124+
125+
[Metrics]
126+
public async Task<APIGatewayProxyResponse> FunctionHandler(APIGatewayProxyRequest apigProxyEvent, ILambdaContext context)
127+
{
128+
Metrics.AddMetric("SuccessfulBooking", 1, MetricUnit.Count);
129+
...
130+
}
131+
// --8<-- [end:function_name_configure]

‎docs/snippets/metrics/AspNetCore.cs‎

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
// This file is referenced by docs/core/metrics.md
2+
// via pymdownx.snippets (mkdocs).
3+
4+
namespace AWS.Lambda.Powertools.Docs.Snippets.Metrics;
5+
6+
// --8<-- [start:use_metrics_middleware]
7+
8+
using AWS.Lambda.Powertools.Metrics.AspNetCore.Http;
9+
10+
var builder = WebApplication.CreateBuilder(args);
11+
12+
// Configure metrics
13+
builder.Services.AddSingleton<IMetrics>(_ => new MetricsBuilder()
14+
.WithNamespace("MyApi") // Namespace for the metrics
15+
.WithService("WeatherService") // Service name for the metrics
16+
.WithCaptureColdStart(true) // Capture cold start metrics
17+
.WithDefaultDimensions(new Dictionary<string, string> // Default dimensions for the metrics
18+
{
19+
{"Environment", "Prod"},
20+
{"Another", "One"}
21+
})
22+
.Build()); // Build the metrics
23+
24+
builder.Services.AddAWSLambdaHosting(LambdaEventSource.RestApi);
25+
26+
var app = builder.Build();
27+
28+
app.UseMetrics(); // Add the metrics middleware
29+
30+
app.MapGet("/powertools", (IMetrics metrics) =>
31+
{
32+
// add custom metrics
33+
metrics.AddMetric("MyCustomMetric", 1, MetricUnit.Count);
34+
// flush metrics - this is required to ensure metrics are sent to CloudWatch
35+
metrics.Flush();
36+
});
37+
38+
app.Run();
39+
// --8<-- [end:use_metrics_middleware]
40+
41+
// --8<-- [start:use_metrics_method]
42+
/// <summary>
43+
/// Adds a metrics middleware to the specified application builder.
44+
/// This will capture cold start (if CaptureColdStart is enabled) metrics and flush metrics on function exit.
45+
/// </summary>
46+
/// <param name="app">The application builder to add the metrics middleware to.</param>
47+
/// <returns>The application builder with the metrics middleware added.</returns>
48+
public static IApplicationBuilder UseMetrics(this IApplicationBuilder app)
49+
{
50+
app.UseMiddleware<MetricsMiddleware>();
51+
return app;
52+
}
53+
// --8<-- [end:use_metrics_method]
54+
55+
// --8<-- [start:with_metrics_filter]
56+
57+
using AWS.Lambda.Powertools.Metrics;
58+
using AWS.Lambda.Powertools.Metrics.AspNetCore.Http;
59+
60+
var builder = WebApplication.CreateBuilder(args);
61+
62+
// Configure metrics
63+
builder.Services.AddSingleton<IMetrics>(_ => new MetricsBuilder()
64+
.WithNamespace("MyApi") // Namespace for the metrics
65+
.WithService("WeatherService") // Service name for the metrics
66+
.WithCaptureColdStart(true) // Capture cold start metrics
67+
.WithDefaultDimensions(new Dictionary<string, string> // Default dimensions for the metrics
68+
{
69+
{"Environment", "Prod"},
70+
{"Another", "One"}
71+
})
72+
.Build()); // Build the metrics
73+
74+
// Add AWS Lambda support. When the application is run in Lambda, Kestrel is swapped out as the web server with Amazon.Lambda.AspNetCoreServer. This
75+
// package will act as the web server translating requests and responses between the Lambda event source and ASP.NET Core.
76+
builder.Services.AddAWSLambdaHosting(LambdaEventSource.RestApi);
77+
78+
var app = builder.Build();
79+
80+
app.MapGet("/powertools", (IMetrics metrics) =>
81+
{
82+
// add custom metrics
83+
metrics.AddMetric("MyCustomMetric", 1, MetricUnit.Count);
84+
// flush metrics - this is required to ensure metrics are sent to CloudWatch
85+
metrics.Flush();
86+
})
87+
.WithMetrics();
88+
89+
app.Run();
90+
// --8<-- [end:with_metrics_filter]
91+
92+
// --8<-- [start:with_metrics_method]
93+
/// <summary>
94+
/// Adds a metrics filter to the specified route handler builder.
95+
/// This will capture cold start (if CaptureColdStart is enabled) metrics and flush metrics on function exit.
96+
/// </summary>
97+
/// <param name="builder">The route handler builder to add the metrics filter to.</param>
98+
/// <returns>The route handler builder with the metrics filter added.</returns>
99+
public static RouteHandlerBuilder WithMetrics(this RouteHandlerBuilder builder)
100+
{
101+
builder.AddEndpointFilter<MetricsFilter>();
102+
return builder;
103+
}
104+
// --8<-- [end:with_metrics_method]

‎docs/snippets/metrics/CaptureColdStart.cs‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
// This file is referenced by docs/core/metrics.md
2+
// via pymdownx.snippets (mkdocs).
3+
4+
namespace AWS.Lambda.Powertools.Docs.Snippets.Metrics;
5+
6+
// --8<-- [start:capture_cold_start_attribute]
7+
using AWS.Lambda.Powertools.Metrics;
8+
9+
public class Function {
10+
11+
[Metrics(CaptureColdStart = true)]
12+
public async Task<APIGatewayProxyResponse> FunctionHandler(APIGatewayProxyRequest apigProxyEvent, ILambdaContext context)
13+
{
14+
...
15+
// --8<-- [end:capture_cold_start_attribute]
16+
17+
// --8<-- [start:capture_cold_start_builder]
18+
using AWS.Lambda.Powertools.Metrics;
19+
20+
public class Function {
21+
private readonly IMetrics _metrics;
22+
23+
public Function()
24+
{
25+
_metrics = new MetricsBuilder()
26+
.WithCaptureColdStart(true)
27+
.WithService("testService")
28+
.WithNamespace("dotnet-powertools-test")
29+
}
30+
31+
[Metrics]
32+
public async Task<APIGatewayProxyResponse> FunctionHandler(APIGatewayProxyRequest apigProxyEvent, ILambdaContext context)
33+
{
34+
_metrics.AddMetric("SuccessfulBooking", 1, MetricUnit.Count);
35+
...
36+
}
37+
// --8<-- [end:capture_cold_start_builder]
38+
39+
// --8<-- [start:capture_cold_start_configure]
40+
using AWS.Lambda.Powertools.Metrics;
41+
42+
public class Function {
43+
44+
public Function()
45+
{
46+
Metrics.Configure(options =>
47+
{
48+
options.Namespace = "dotnet-powertools-test";
49+
options.Service = "testService";
50+
options.CaptureColdStart = true;
51+
});
52+
}
53+
54+
[Metrics]
55+
public async Task<APIGatewayProxyResponse> FunctionHandler(APIGatewayProxyRequest apigProxyEvent, ILambdaContext context)
56+
{
57+
Metrics.AddMetric("SuccessfulBooking", 1, MetricUnit.Count);
58+
...
59+
}
60+
// --8<-- [end:capture_cold_start_configure]

‎docs/snippets/metrics/CreatingMetrics.cs‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
// This file is referenced by docs/core/metrics.md
2+
// via pymdownx.snippets (mkdocs).
3+
4+
namespace AWS.Lambda.Powertools.Docs.Snippets.Metrics;
5+
6+
// --8<-- [start:creating_metrics]
7+
using AWS.Lambda.Powertools.Metrics;
8+
9+
public class Function {
10+
11+
[Metrics(Namespace = "ExampleApplication", Service = "Booking")]
12+
public async Task<APIGatewayProxyResponse> FunctionHandler(APIGatewayProxyRequest apigProxyEvent, ILambdaContext context)
13+
{
14+
Metrics.AddMetric("SuccessfulBooking", 1, MetricUnit.Count);
15+
}
16+
}
17+
// --8<-- [end:creating_metrics]
18+
19+
// --8<-- [start:metrics_with_dimensions]
20+
using AWS.Lambda.Powertools.Metrics;
21+
22+
public class Function {
23+
24+
[Metrics(Namespace = "ExampleApplication", Service = "Booking")]
25+
public async Task<APIGatewayProxyResponse> FunctionHandler(APIGatewayProxyRequest apigProxyEvent, ILambdaContext context)
26+
{
27+
Metrics.AddDimension("Environment","Prod");
28+
Metrics.AddMetric("SuccessfulBooking", 1, MetricUnit.Count);
29+
}
30+
}
31+
// --8<-- [end:metrics_with_dimensions]
32+
33+
// --8<-- [start:high_resolution_metrics]
34+
using AWS.Lambda.Powertools.Metrics;
35+
36+
public class Function {
37+
38+
[Metrics(Namespace = "ExampleApplication", Service = "Booking")]
39+
public async Task<APIGatewayProxyResponse> FunctionHandler(APIGatewayProxyRequest apigProxyEvent, ILambdaContext context)
40+
{
41+
// Publish a metric with standard resolution i.e. StorageResolution = 60
42+
Metrics.AddMetric("SuccessfulBooking", 1, MetricUnit.Count, MetricResolution.Standard);
43+
44+
// Publish a metric with high resolution i.e. StorageResolution = 1
45+
Metrics.AddMetric("FailedBooking", 1, MetricUnit.Count, MetricResolution.High);
46+
47+
// The last parameter (storage resolution) is optional
48+
Metrics.AddMetric("SuccessfulUpgrade", 1, MetricUnit.Count);
49+
}
50+
}
51+
// --8<-- [end:high_resolution_metrics]

0 commit comments

Comments
 (0)