From Code to Community: Sponsoring The Perl and Raku Conference 2025 Learn more

JJATRIA / OpenTelemetry-0.029 / lib / OpenTelemetry / Instrumentation / namespace.pod 

            

              
—
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133

              
=encoding utf8
=head1 NAME
OpenTelemetry::Instrumentation::namespace - OpenTelemetry instrumentation for a namespace
=head1 SYNOPSIS
    # This instrumentation is EXPERIMENTAL
    use OpenTelemetry::Instrumentation 'namespace' => {
        include => {
            paths => [(
                lib/Local
            )],
        },
        exclude => {
            paths => [qw(
                lib/Local/Secret
            )],
            subroutines => {
                'Some::Package' => [qw(
                    low_level
                )],
            },
        },
    };
=head1 DESCRIPTION
See L<OpenTelemetry::Instrumentation> for more details.
Since this is a core module, it's included in the L<OpenTelemetry> core
distribution as well.
=head1 CONFIGURATION
=head2 include / exclude
The C<include> and C<exclude> sections control the package and subroutines
that are considered to be relevant by the monitoring code. Fields in the
C<exclude> section take precedence.
=head3 paths
This field should be set to list of literal paths or path segments. Any code
that is loaded from those paths will be included or excluded depending on what
section this was under.
For example:
    include => {
        paths => [qw(
            lib/Local
            lib/Test
        )],
    },
    exclude => {
        paths => [qw(
            lib/Local/Secret
        )],
    },
would make all the code that is loaded from C<lib/Local> and C<lib/Test>,
except the code loaded from C<lib/Local/Secret>, relevant for monitoring.
=head3 subpackages
Perl allows multiple packages to be defined inside the same file, so that
importing one file makes all of those packages available, without the
subpackages ever being explicitly loaded. Under normal circumstances, this
makes these packages invisible to the approach in this instrumentation.
This key makes it possible to specify packages that should be wrapped for
monitoring whenever we detect another packages being loaded.
This field should be set to a hash where the keys are package names and
the values are lists of packages to be wrapped whenever the parent is.
For example:
    include => {
        subpackages => {
            'Local::Foo' => [qw(
                Local::Foo::Bar
            )],
        },
    },
This mapping has no meaning under C<exclude>, and is ignored in that case.
=head3 subroutines
In some cases, some specific subroutines are of interest even though they
are defined in packages that would otherwise not be eligible for reporting.
This field makes it possible to mark those subroutines as explicitly
relevant or irrelevant depending on the section this is under. If under
C<include>, these subroutines will always be wrapped; while under C<exclude>
they will I<never> be.
This field should be set to a hash where the keys are package names and
the values are lists of subroutine names.
For example:
    include => {
        subroutines => {
            'Local::Splines' => [qw(
                reticulate
            )],
        },
    },
    exclude => {
        subroutines => {
            'Local::Splines' => [qw(
                frobligate
            )],
        },
    },
This would make C<Local::Splines::reticulate> I<always> be wrapped, even
if C<Local::Splines> was loaded from a path that was not otherwise
specified as relevant. Likewise, C<Local::Splines::frobligate> would never
be wrapped, even if C<Local::Splines> was marked as relevant through some
other method.
=head1 COPYRIGHT
This software is copyright (c) 2023 by José Joaquín Atria.
This is free software; you can redistribute it and/or modify it under the same
terms as the Perl 5 programming language system itself.