@@ -4,34 +4,9 @@ Runs analysis on instrumentation modules in order to generate documentation.
4
4
5
5
## How to use
6
6
7
- Until this process is ready for all instrumentations, each module will be modified to include a
8
- system property configured for when the tests run:
9
-
10
- ``` kotlin
11
- tasks {
12
- test {
13
- systemProperty(" collectMetadata" , findProperty(" collectMetadata" )?.toString() ? : " false" )
14
- .. .
15
- }
16
- }
17
- ```
18
-
19
- Prior to running the DocGeneratorApplication, run the following command to collect metadata:
20
-
21
- * Run tests to collect metadata
22
- * ` ./gradlew test -collectMetadata=true `
23
- * Run the doc generator
24
- * ` ./gradlew :instrumentation-docs:generateDocs `
7
+ Run the doc generator:
25
8
26
- You can also use an environment variable to set it for the entire suite:
27
-
28
- ` COLLECT_METADATA=true ./gradlew test `
29
-
30
- or use the helper script that will run only the currently supported tests:
31
-
32
- ``` bash
33
- ./instrumentation-docs/collect.sh
34
- ```
9
+ ` ./gradlew :instrumentation-docs:generateDocs `
35
10
36
11
## Instrumentation Hierarchy
37
12
@@ -82,12 +57,7 @@ public class SpringWebInstrumentationModule extends InstrumentationModule
82
57
* target_versions
83
58
* List of supported versions by the module, broken down by `library` or `javaagent` support
84
59
* scope
85
- * The scope of the instrumentation, including the name, version, schemaUrl and attributes
86
- * metrics
87
- * List of metrics that the instrumentation module collects, including the metric name, description, type, and attributes
88
- * span_data
89
- * List of span types that are emitted (internal, client, server)
90
- * List of span data that the instrumentation collects, including the attribute name and type
60
+ * Name : The scope name of the instrumentation, `io. opentelemetry. {instrumentation name}`
91
61
92
62
## Methodology
93
63
@@ -110,57 +80,10 @@ We parse gradle files in order to determine the target versions.
110
80
- Library versions are determined by the library dependency versions
111
81
- when available, latestDepTestLibrary is used to determine the latest supported version
112
82
113
- ### Scope , Span Data , and Metrics
114
-
115
- Since many of our tests generate this information, we can hook into the InstrumentationTestRunner
116
- class and collect the metrics, spans, and scope generated. We can then leverage the `afterTestClass()`
117
- in the Agent and library test runners to then write this information into temporary files.
118
-
119
- The data is written into a `.telemetry` directory in the root of the instrumentation module. This data
120
- will be excluded from git and just generated on demand.
83
+ ### Scope
121
84
122
- Since metadata can be generated by multiple classes, we will generate a file per class.
85
+ For now, the scope name is the only value that is implemented in our instrumentations. The scope
86
+ name is determined by the instrumentation module name: `io. opentelemetry. {instrumentation name}`
123
87
124
- Example output:
125
-
126
- ```
127
- clickhouse:
128
- instrumentations:
129
- - name: clickhouse-client-0.5
130
- description: Instruments the V1 ClickHouseClient, providing database client spans
131
- and metrics.
132
- srcPath: instrumentation/clickhouse-client-0.5
133
- target_versions:
134
- javaagent:
135
- - com.clickhouse.client:clickhouse-client:[0.5.0,)
136
- metrics:
137
- - name: db.client.operation.duration
138
- description: Duration of database client operations.
139
- type: HISTOGRAM
140
- unit: s
141
- attributes:
142
- - name: db.namespace
143
- type: STRING
144
- - name: db.operation.name
145
- type: STRING
146
- - name: db.system.name
147
- type: STRING
148
- - name: server.address
149
- type: STRING
150
- - name: server.port
151
- type: LONG
152
- span_data:
153
- attributes:
154
- - name: server.address
155
- type: STRING
156
- - name: server.port
157
- type: LONG
158
- - name: db.system.name
159
- type: STRING
160
- - name: db.query.text
161
- type: STRING
162
- - name: db.namespace
163
- type: STRING
164
- - name: db.operation.name
165
- type: STRING
166
- ```
88
+ We will implement gatherers for the schemaUrl and attributes when instrumentations start
89
+ implementing them.
0 commit comments