Skip to content

Commit 2543696

Browse files
tilligtillig
committed
Update to the hierarchy for diagnostics.
1 parent a1c623e commit 2543696

3 files changed

Lines changed: 157 additions & 162 deletions

File tree

‎docs/troubleshooting/index.rst‎

Lines changed: 4 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -30,12 +30,10 @@ Diagnostics
3030
.. toctree::
3131
:hidden:
3232

33-
diagnostics.rst
34-
35-
Autofac has diagnostics support that allows for tracing and metrics to assist in troubleshooting issues with dependency resolution and component activation.
36-
37-
We have :doc:`a page explaining how to hook into diagnostics and do deeper troubleshooting. <diagnostics>`
33+
Tracing <tracing.rst>
34+
Metrics <metrics.rst>
3835

36+
Autofac has diagnostics support that allows for :doc:`tracing <tracing>` and :doc:`metrics <metrics>` to assist in troubleshooting issues with dependency resolution and component activation.
3937

4038
Symbols and Sources
4139
-------------------
@@ -45,7 +43,7 @@ Symbols and Sources
4543

4644
symbols.rst
4745

48-
Autofac publishes its source code and symbols so you can debug right into the Autofac source. See the :doc:`Symbols and Sources <symbols>` page for more information.
46+
Autofac :doc:`publishes its source code and symbols <symbols>` so you can debug right into the Autofac source.
4947

5048
Support
5149
-------

‎docs/troubleshooting/metrics.rst‎

Lines changed: 146 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,146 @@
1+
=======
2+
Metrics
3+
=======
4+
5+
Autofac 9.1 introduced opt-in performance metrics using `System.Diagnostics.Metrics <https://learn.microsoft.com/en-us/dotnet/core/diagnostics/metrics>`_, the standard .NET metrics API. These are separate from ``DiagnosticSource`` tracing - they are counters and histograms rather than per-request event traces.
6+
7+
.. warning::
8+
9+
**Metrics aren't free.** Collecting them will incur a performance hit, so this is **not** something you want to leave on in production. Enable metrics only when you need to measure and tune Autofac's behavior in your application.
10+
11+
If you're interested in tracing to find out why something is wired up how it is, :doc:`Autofac also provides tracing <tracing>`.
12+
13+
Enabling Metrics
14+
----------------
15+
16+
Set the ``AUTOFAC_METRICS`` environment variable to ``true`` or ``1`` before your process starts.
17+
18+
.. code-block:: shell
19+
20+
# Unix/macOS
21+
export AUTOFAC_METRICS=true
22+
23+
# Windows (PowerShell)
24+
$env:AUTOFAC_METRICS = "true"
25+
26+
# Windows (cmd)
27+
set AUTOFAC_METRICS=true
28+
29+
Available Counters
30+
------------------
31+
32+
Metrics are published under the meter name ``autofac`` (version ``1.0.0``). The following instruments are available:
33+
34+
.. list-table::
35+
:header-rows: 1
36+
:widths: 40 15 10 35
37+
38+
* - Name
39+
- Type
40+
- Unit
41+
- Description
42+
* - ``autofac.middleware.duration``
43+
- Histogram
44+
- s
45+
- Time spent executing resolve pipeline middleware.
46+
* - ``autofac.middleware.count``
47+
- Counter
48+
-
49+
- Number of resolve pipeline middleware executions.
50+
* - ``autofac.reflection.activation.duration``
51+
- Histogram
52+
- s
53+
- Time spent activating components via ``ReflectionActivator``.
54+
* - ``autofac.collection.build.duration``
55+
- Histogram
56+
- s
57+
- Time spent materializing implicit collection services.
58+
* - ``autofac.collection.build.count``
59+
- Counter
60+
-
61+
- Number of implicit collection builds performed.
62+
* - ``autofac.collection.build.items``
63+
- Counter
64+
-
65+
- Total elements added to implicit collections.
66+
* - ``autofac.property.injection.duration``
67+
- Histogram
68+
- s
69+
- Time spent performing property injection.
70+
* - ``autofac.property.injection.count``
71+
- Counter
72+
-
73+
- Number of instances that had property injection applied.
74+
* - ``autofac.property.injection.assignments``
75+
- Counter
76+
-
77+
- Number of individual property assignments performed.
78+
* - ``autofac.lock.contention.duration``
79+
- Histogram
80+
- s
81+
- Time threads waited to acquire Autofac internal locks.
82+
* - ``autofac.lock.contention.count``
83+
- Counter
84+
-
85+
- Number of lock contention events observed.
86+
* - ``autofac.lock.contention.total_time``
87+
- Counter
88+
- s
89+
- Cumulative time spent waiting on Autofac locks.
90+
91+
.. note::
92+
93+
The lock contention metrics include per-service and per-lifetime-scope detail in their tags. This can produce high-cardinality data, so be mindful of the storage implications if you forward these to an external metrics backend.
94+
95+
Collecting Metrics
96+
------------------
97+
98+
Because Autofac uses the standard ``System.Diagnostics.Metrics`` API, you can collect these metrics with any compatible tool.
99+
100+
**Using dotnet-counters (CLI)**
101+
102+
The quickest way to spot-check metrics is `dotnet-counters <https://learn.microsoft.com/en-us/dotnet/core/diagnostics/dotnet-counters>`_:
103+
104+
.. code-block:: shell
105+
106+
dotnet-counters monitor --counters autofac --process-id <pid>
107+
108+
**Using MeterListener in code**
109+
110+
You can subscribe programmatically to receive measurement callbacks:
111+
112+
.. sourcecode:: csharp
113+
114+
var listener = new MeterListener();
115+
116+
listener.InstrumentPublished = (instrument, listener) =>
117+
{
118+
if (instrument.Meter.Name == "autofac")
119+
{
120+
listener.EnableMeasurementEvents(instrument);
121+
}
122+
};
123+
124+
listener.SetMeasurementEventCallback<double>((instrument, value, tags, state) =>
125+
{
126+
Console.WriteLine($"{instrument.Name}: {value:F6}s");
127+
});
128+
129+
listener.SetMeasurementEventCallback<long>((instrument, value, tags, state) =>
130+
{
131+
Console.WriteLine($"{instrument.Name}: {value}");
132+
});
133+
134+
listener.Start();
135+
136+
**Using OpenTelemetry**
137+
138+
If your application already uses `OpenTelemetry <https://opentelemetry.io/docs/languages/dotnet/>`_, add the ``autofac`` meter to your ``MeterProvider``:
139+
140+
.. sourcecode:: csharp
141+
142+
using var meterProvider = Sdk.CreateMeterProviderBuilder()
143+
.AddMeter("autofac")
144+
// Add your exporter of choice:
145+
.AddConsoleExporter()
146+
.Build();

docs/troubleshooting/diagnostics.rst renamed to docs/troubleshooting/tracing.rst

Lines changed: 7 additions & 156 deletions
Original file line numberDiff line numberDiff line change
@@ -1,22 +1,17 @@
1-
===========
2-
Diagnostics
3-
===========
1+
=======
2+
Tracing
3+
=======
44

5-
Autofac provides some diagnostics capabilities that allow you to monitor and trace the resolution of components within the container. This can help for troubleshooting issues with component registration and resolution, understanding the lifetime of components, and optimizing performance.
5+
Autofac provides diagnostics support that allows you to monitor and trace the resolution of components within the container. This can help with troubleshooting issues in component registration and resolution, understanding component lifetimes, and optimizing performance.
66

77
.. warning::
88

9-
Metrics and diagnostics aren't free. You will get better performance if you **don't** have a diagnostic listener attached to the container and if you **don't** have counters being collected. Further, tracers like ``DefaultDiagnosticTracer`` that generate a full trace of an operation will increase memory and resource usage as they have to hold onto data during the entire resolve operation in order to generate a complete trace. It is recommended you only use diagnostics in a non-production environment; or use diagnostics listeners that handle individual events without tracking full operations.
10-
11-
.. contents:: Diagnostics Options
12-
:local:
13-
:depth: 1
14-
15-
Tracing
16-
=======
9+
**Tracing isn't free.** You will get better performance if you **don't** have a diagnostic listener attached to the container. Further, tracers like ``DefaultDiagnosticTracer`` that generate a full trace of an operation will increase memory and resource usage as they have to hold onto data during the entire resolve operation in order to generate a complete trace. It is recommended you only use diagnostics in a non-production environment; or use diagnostics listeners that handle individual events without tracking full operations.
1710

1811
Autofac 6.0 introduced diagnostics support in the form of `System.Diagnostics.DiagnosticSource <https://docs.microsoft.com/en-us/dotnet/api/system.diagnostics.diagnosticsource?view=netcore-3.1>`_. This allows you to intercept diagnostic events from Autofac.
1912

13+
If you're interested in metrics for performance measurement, :doc:`Autofac also provides metrics <metrics>`.
14+
2015
Quick Start
2116
-----------
2217

@@ -359,147 +354,3 @@ When you get this low, you can control the subscriptions for your events separat
359354
// the tracer should get an event.
360355
var tracer = new ConsoleOperationTracer();
361356
container.DiagnosticSource.Subscribe(tracer, e => e == "Autofac.Operation.Start");
362-
363-
Metrics
364-
=======
365-
366-
Autofac 9.1 introduced opt-in performance metrics using `System.Diagnostics.Metrics <https://learn.microsoft.com/en-us/dotnet/core/diagnostics/metrics>`_, the standard .NET metrics API. These are separate from the ``DiagnosticSource``-based tracing above - they are lightweight, aggregatable counters and histograms rather than per-request event traces.
367-
368-
.. warning::
369-
370-
Metrics aren't free. Collecting them will incur a performance hit, so this is **not** something you want to leave on in production. Enable metrics only when you need to measure and tune Autofac's behavior in your application.
371-
372-
Enabling Metrics
373-
----------------
374-
375-
Set the ``AUTOFAC_METRICS`` environment variable to ``true`` or ``1`` before your process starts. The variable is checked once at startup; changing it at runtime has no effect.
376-
377-
.. code-block:: shell
378-
379-
# Unix/macOS
380-
export AUTOFAC_METRICS=true
381-
382-
# Windows (PowerShell)
383-
$env:AUTOFAC_METRICS = "true"
384-
385-
# Windows (cmd)
386-
set AUTOFAC_METRICS=true
387-
388-
Available Counters
389-
------------------
390-
391-
Metrics are published under the meter name ``autofac`` (version ``1.0.0``). The following instruments are available:
392-
393-
.. list-table::
394-
:header-rows: 1
395-
:widths: 40 15 10 35
396-
397-
* - Name
398-
- Type
399-
- Unit
400-
- Description
401-
* - ``autofac.middleware.duration``
402-
- Histogram
403-
- s
404-
- Time spent executing resolve pipeline middleware.
405-
* - ``autofac.middleware.count``
406-
- Counter
407-
-
408-
- Number of resolve pipeline middleware executions.
409-
* - ``autofac.reflection.activation.duration``
410-
- Histogram
411-
- s
412-
- Time spent activating components via ``ReflectionActivator``.
413-
* - ``autofac.collection.build.duration``
414-
- Histogram
415-
- s
416-
- Time spent materializing implicit collection services.
417-
* - ``autofac.collection.build.count``
418-
- Counter
419-
-
420-
- Number of implicit collection builds performed.
421-
* - ``autofac.collection.build.items``
422-
- Counter
423-
-
424-
- Total elements added to implicit collections.
425-
* - ``autofac.property.injection.duration``
426-
- Histogram
427-
- s
428-
- Time spent performing property injection.
429-
* - ``autofac.property.injection.count``
430-
- Counter
431-
-
432-
- Number of instances that had property injection applied.
433-
* - ``autofac.property.injection.assignments``
434-
- Counter
435-
-
436-
- Number of individual property assignments performed.
437-
* - ``autofac.lock.contention.duration``
438-
- Histogram
439-
- s
440-
- Time threads waited to acquire Autofac internal locks.
441-
* - ``autofac.lock.contention.count``
442-
- Counter
443-
-
444-
- Number of lock contention events observed.
445-
* - ``autofac.lock.contention.total_time``
446-
- Counter
447-
- s
448-
- Cumulative time spent waiting on Autofac locks.
449-
450-
.. note::
451-
452-
The lock contention metrics include per-service and per-lifetime-scope detail in their tags. This can produce high-cardinality data, so be mindful of the storage implications if you forward these to an external metrics backend.
453-
454-
Collecting Metrics
455-
------------------
456-
457-
Because Autofac uses the standard ``System.Diagnostics.Metrics`` API, you can collect these metrics with any compatible tool.
458-
459-
**Using dotnet-counters (CLI)**
460-
461-
The quickest way to spot-check metrics is `dotnet-counters <https://learn.microsoft.com/en-us/dotnet/core/diagnostics/dotnet-counters>`_:
462-
463-
.. code-block:: shell
464-
465-
dotnet-counters monitor --counters autofac --process-id <pid>
466-
467-
**Using MeterListener in code**
468-
469-
You can subscribe programmatically to receive measurement callbacks:
470-
471-
.. sourcecode:: csharp
472-
473-
var listener = new MeterListener();
474-
475-
listener.InstrumentPublished = (instrument, listener) =>
476-
{
477-
if (instrument.Meter.Name == "autofac")
478-
{
479-
listener.EnableMeasurementEvents(instrument);
480-
}
481-
};
482-
483-
listener.SetMeasurementEventCallback<double>((instrument, value, tags, state) =>
484-
{
485-
Console.WriteLine($"{instrument.Name}: {value:F6}s");
486-
});
487-
488-
listener.SetMeasurementEventCallback<long>((instrument, value, tags, state) =>
489-
{
490-
Console.WriteLine($"{instrument.Name}: {value}");
491-
});
492-
493-
listener.Start();
494-
495-
**Using OpenTelemetry**
496-
497-
If your application already uses `OpenTelemetry <https://opentelemetry.io/docs/languages/dotnet/>`_, add the ``autofac`` meter to your ``MeterProvider``:
498-
499-
.. sourcecode:: csharp
500-
501-
using var meterProvider = Sdk.CreateMeterProviderBuilder()
502-
.AddMeter("autofac")
503-
// Add your exporter of choice:
504-
.AddConsoleExporter()
505-
.Build();

0 commit comments

Comments
 (0)