@oas-tools/oas-telemetry 0.6.2 → 0.7.0-alpha.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +442 -442
- package/dist/{config.cjs → cjs/config.cjs} +6 -7
- package/dist/{exporters → cjs/exporters}/InMemoryDBMetricsExporter.cjs +5 -40
- package/dist/cjs/exporters/InMemoryDbExporter.cjs +87 -0
- package/dist/cjs/exporters/InMemoryLogRecordExporter.cjs +110 -0
- package/dist/{exporters → cjs/exporters}/consoleExporter.cjs +2 -7
- package/dist/{exporters → cjs/exporters}/dynamicExporter.cjs +12 -19
- package/dist/cjs/index.cjs +43 -0
- package/dist/cjs/instrumentation/index.cjs +28 -0
- package/dist/cjs/instrumentation/logs.cjs +46 -0
- package/dist/cjs/instrumentation/metrics.cjs +27 -0
- package/dist/cjs/instrumentation/traces.cjs +19 -0
- package/dist/{openTelemetry.cjs → cjs/openTelemetry.cjs} +6 -8
- package/dist/{systemMetrics.cjs → cjs/systemMetrics.cjs} +7 -7
- package/dist/cjs/tlm-ai/agent.cjs +79 -0
- package/dist/cjs/tlm-ai/aiController.cjs +69 -0
- package/dist/cjs/tlm-ai/aiRoutes.cjs +13 -0
- package/dist/cjs/tlm-ai/knownMicroservices.cjs +13 -0
- package/dist/cjs/tlm-ai/tools.cjs +504 -0
- package/dist/{routes/authRoutes.cjs → cjs/tlm-auth/authController.cjs} +21 -28
- package/dist/{middleware → cjs/tlm-auth}/authMiddleware.cjs +1 -1
- package/dist/cjs/tlm-auth/authRoutes.cjs +14 -0
- package/dist/cjs/tlm-log/logController.cjs +55 -0
- package/dist/cjs/tlm-log/logRoutes.cjs +13 -0
- package/dist/{routes → cjs/tlm-metric}/metricsRoutes.cjs +1 -2
- package/dist/{controllers → cjs/tlm-plugin}/pluginController.cjs +31 -41
- package/dist/cjs/tlm-plugin/pluginRoutes.cjs +13 -0
- package/dist/{controllers/telemetryController.cjs → cjs/tlm-trace/traceController.cjs} +8 -19
- package/dist/cjs/tlm-trace/traceRoutes.cjs +17 -0
- package/dist/cjs/tlm-ui/uiController.cjs +27 -0
- package/dist/cjs/tlm-ui/uiRoutes.cjs +31 -0
- package/dist/cjs/tlm-util/utilController.cjs +63 -0
- package/dist/cjs/tlm-util/utilRoutes.cjs +12 -0
- package/dist/cjs/tlmRoutes.cjs +79 -0
- package/dist/cjs/types/index.cjs +8 -0
- package/dist/cjs/utils/circular.cjs +90 -0
- package/dist/cjs/utils/logger.cjs +28 -0
- package/{src → dist/esm}/config.js +20 -23
- package/{src → dist/esm}/exporters/InMemoryDBMetricsExporter.js +57 -111
- package/dist/esm/exporters/InMemoryDbExporter.js +87 -0
- package/dist/esm/exporters/InMemoryLogRecordExporter.js +95 -0
- package/{src → dist/esm}/exporters/consoleExporter.js +38 -47
- package/{src → dist/esm}/exporters/dynamicExporter.js +50 -62
- package/dist/esm/index.js +39 -0
- package/dist/esm/instrumentation/index.js +26 -0
- package/dist/esm/instrumentation/logs.js +34 -0
- package/dist/esm/instrumentation/metrics.js +18 -0
- package/dist/esm/instrumentation/traces.js +12 -0
- package/{src → dist/esm}/openTelemetry.js +50 -58
- package/dist/esm/systemMetrics.js +82 -0
- package/dist/esm/tlm-ai/agent.js +68 -0
- package/dist/esm/tlm-ai/aiController.js +45 -0
- package/dist/esm/tlm-ai/aiRoutes.js +7 -0
- package/dist/esm/tlm-ai/knownMicroservices.js +5 -0
- package/dist/esm/tlm-ai/tools.js +490 -0
- package/dist/esm/tlm-auth/authController.js +41 -0
- package/{src/middleware → dist/esm/tlm-auth}/authMiddleware.js +12 -14
- package/dist/esm/tlm-auth/authRoutes.js +7 -0
- package/dist/esm/tlm-log/logController.js +36 -0
- package/dist/esm/tlm-log/logRoutes.js +7 -0
- package/{src/controllers → dist/esm/tlm-metric}/metricsController.js +28 -30
- package/{src/routes → dist/esm/tlm-metric}/metricsRoutes.js +8 -15
- package/{src/controllers → dist/esm/tlm-plugin}/pluginController.js +103 -115
- package/dist/esm/tlm-plugin/pluginRoutes.js +7 -0
- package/dist/esm/tlm-trace/traceController.js +54 -0
- package/dist/esm/tlm-trace/traceRoutes.js +11 -0
- package/dist/esm/tlm-ui/uiController.js +20 -0
- package/dist/esm/tlm-ui/uiRoutes.js +23 -0
- package/dist/esm/tlm-util/utilController.js +57 -0
- package/dist/esm/tlm-util/utilRoutes.js +6 -0
- package/dist/esm/tlmRoutes.js +72 -0
- package/dist/esm/types/index.js +4 -0
- package/dist/esm/utils/circular.js +84 -0
- package/dist/esm/utils/logger.js +19 -0
- package/dist/types/config.d.ts +6 -0
- package/dist/types/exporters/InMemoryDBMetricsExporter.d.ts +15 -0
- package/dist/types/exporters/InMemoryDbExporter.d.ts +24 -0
- package/dist/types/exporters/InMemoryLogRecordExporter.d.ts +27 -0
- package/dist/types/exporters/consoleExporter.d.ts +13 -0
- package/dist/types/exporters/dynamicExporter.d.ts +25 -0
- package/dist/types/index.d.ts +8 -0
- package/dist/types/instrumentation/index.d.ts +1 -0
- package/dist/types/instrumentation/logs.d.ts +1 -0
- package/dist/types/instrumentation/metrics.d.ts +1 -0
- package/dist/types/instrumentation/traces.d.ts +1 -0
- package/dist/types/openTelemetry.d.ts +1 -0
- package/dist/types/systemMetrics.d.ts +26 -0
- package/dist/types/tlm-ai/agent.d.ts +1 -0
- package/dist/types/tlm-ai/aiController.d.ts +4 -0
- package/dist/types/tlm-ai/aiRoutes.d.ts +2 -0
- package/dist/types/tlm-ai/knownMicroservices.d.ts +6 -0
- package/dist/types/tlm-ai/tools.d.ts +45 -0
- package/dist/types/tlm-auth/authController.d.ts +4 -0
- package/dist/types/tlm-auth/authMiddleware.d.ts +2 -0
- package/dist/types/tlm-auth/authRoutes.d.ts +2 -0
- package/dist/types/tlm-log/logController.d.ts +4 -0
- package/dist/types/tlm-log/logRoutes.d.ts +2 -0
- package/dist/types/tlm-metric/metricsController.d.ts +4 -0
- package/dist/types/tlm-metric/metricsRoutes.d.ts +2 -0
- package/dist/types/tlm-plugin/pluginController.d.ts +3 -0
- package/dist/types/tlm-plugin/pluginRoutes.d.ts +2 -0
- package/dist/types/tlm-trace/traceController.d.ts +7 -0
- package/dist/types/tlm-trace/traceRoutes.d.ts +2 -0
- package/dist/types/tlm-ui/uiController.d.ts +8 -0
- package/dist/types/tlm-ui/uiRoutes.d.ts +2 -0
- package/dist/types/tlm-util/utilController.d.ts +3 -0
- package/dist/types/tlm-util/utilRoutes.d.ts +2 -0
- package/dist/types/tlmRoutes.d.ts +2 -0
- package/dist/types/types/index.d.ts +56 -0
- package/dist/types/utils/circular.d.ts +31 -0
- package/dist/types/utils/logger.d.ts +9 -0
- package/dist/ui/assets/index-BNhZBPi2.css +1 -0
- package/dist/ui/assets/index-DxGAMrAl.js +401 -0
- package/dist/ui/index.html +14 -0
- package/dist/ui/vite.svg +1 -0
- package/package.json +80 -77
- package/dist/controllers/uiController.cjs +0 -78
- package/dist/exporters/InMemoryDbExporter.cjs +0 -178
- package/dist/index.cjs +0 -110
- package/dist/routes/telemetryRoutes.cjs +0 -31
- package/dist/services/uiService.cjs +0 -1520
- package/src/controllers/telemetryController.js +0 -69
- package/src/controllers/uiController.js +0 -69
- package/src/dev/ui/login.html +0 -32
- package/src/exporters/InMemoryDbExporter.js +0 -181
- package/src/index.js +0 -121
- package/src/routes/authRoutes.js +0 -53
- package/src/routes/telemetryRoutes.js +0 -38
- package/src/services/uiService.js +0 -1520
- package/src/systemMetrics.js +0 -102
- /package/dist/{controllers → cjs/tlm-metric}/metricsController.cjs +0 -0
package/README.md
CHANGED
|
@@ -1,442 +1,442 @@
|
|
|
1
|
-
# OAS TELEMETRY
|
|
2
|
-
|
|
3
|
-
**OAS Telemetry** offers an express middleware designed for collecting telemetry data using **Open Telemetry** in applications built using the **OpenAPI Specification (OAS)**. This middleware allows developers to easily incorporate telemetry functionality into their APIs.
|
|
4
|
-
|
|
5
|
-
**OAS Telemetry** provides a set of endpoints that can be accessed to perform various actions related to telemetry data, such as starting and stopping data collection, resetting telemetry data, listing collected data, and searching for specific telemetry records. These endpoints can be easily integrated into an **Express.js** application, providing developers with a convenient way to manage and analyze telemetry data.
|
|
6
|
-
|
|
7
|
-
Additionally, **OAS Telemetry** offers customization options, allowing developers to configure the telemetry middleware according to their specific requirements.
|
|
8
|
-
|
|
9
|
-
Overall, **OAS Telemetry** will serve as a valuable tool for developers looking to gain insights into the operation and performance of their **OAS-based APIs**, enabling them to monitor, debug, and optimize their applications effectively.
|
|
10
|
-
|
|
11
|
-
The package now supports both **ES Module (ESM)** and **CommonJS (CJS)** formats, making it compatible with a wide range of applications. Furthermore, **OAS Telemetry** provides a range of plugins to extend its functionality
|
|
12
|
-
|
|
13
|
-
## Usage
|
|
14
|
-
|
|
15
|
-
This section provides an overview of how to install and integrate **OAS Telemetry** into your EXISTING **Express.js** application. If you want to create a new example express application with **OAS Telemetry** integrated, refer to the [Full Examples](#full-examples) section at the end of this document.
|
|
16
|
-
|
|
17
|
-
First, install the package using npm:
|
|
18
|
-
|
|
19
|
-
```sh
|
|
20
|
-
npm install @oas-tools/oas-telemetry
|
|
21
|
-
```
|
|
22
|
-
|
|
23
|
-
You can integrate the middleware into your Express application. The `spec` option is the OpenAPI Specification (OAS) content in JSON or YAML format. While this configuration is optional, it is recommended for the UI to function correctly.
|
|
24
|
-
|
|
25
|
-
### Using ES Modules (ESM)
|
|
26
|
-
|
|
27
|
-
Add the following lines to your `index.js` file:
|
|
28
|
-
|
|
29
|
-
```js
|
|
30
|
-
// This import MUST be at the top of the file
|
|
31
|
-
import oasTelemetry from '@oas-tools/oas-telemetry';
|
|
32
|
-
import { readFileSync } from 'fs';
|
|
33
|
-
|
|
34
|
-
// ...rest of your code here creating an express app
|
|
35
|
-
|
|
36
|
-
app.use(oasTelemetry({
|
|
37
|
-
spec: readFileSync('./spec/oas.yaml', { encoding: 'utf8', flag: 'r' })
|
|
38
|
-
}));
|
|
39
|
-
```
|
|
40
|
-
|
|
41
|
-
### Using CommonJS
|
|
42
|
-
|
|
43
|
-
Add the following lines to your `index.js` file:
|
|
44
|
-
|
|
45
|
-
```js
|
|
46
|
-
// This require MUST be at the top of the file
|
|
47
|
-
const oasTelemetry = require('@oas-tools/oas-telemetry');
|
|
48
|
-
const { readFileSync } = require('fs');
|
|
49
|
-
|
|
50
|
-
// ...rest of your code here creating an express app
|
|
51
|
-
|
|
52
|
-
app.use(oasTelemetry({
|
|
53
|
-
spec: readFileSync('./spec/oas.yaml', { encoding: 'utf8', flag: 'r' })
|
|
54
|
-
}));
|
|
55
|
-
```
|
|
56
|
-
|
|
57
|
-
For complete examples of a working API with OAS Telemetry enabled, refer to the [Full Examples](#full-examples) section at the end of this document.
|
|
58
|
-
|
|
59
|
-
## Custom Configuration
|
|
60
|
-
|
|
61
|
-
You can also customize the telemetry configuration by passing options to the middleware function. For example:
|
|
62
|
-
|
|
63
|
-
```js
|
|
64
|
-
const customTelemetryConfig = {
|
|
65
|
-
spec: /* OAS content in json or yaml */, // Highly recommended
|
|
66
|
-
baseURL: "/custom-telemetry", //default is "/telemetry"
|
|
67
|
-
autoActivate: false, //default is true, whether to start telemetry data collection automatically
|
|
68
|
-
authEnabled: true, //default is false
|
|
69
|
-
apiKeyMaxAge: 1000 * 60 * 30, // 30 minutes
|
|
70
|
-
password: "custom-password", //default is "oas-telemetry-password"
|
|
71
|
-
jwtSecret: "custom-secret", //default is "oas-telemetry-secret"
|
|
72
|
-
exporter: myCustomExporter, // Experimental, just for devs
|
|
73
|
-
};
|
|
74
|
-
|
|
75
|
-
app.use(oasTelemetry(customTelemetryConfig));
|
|
76
|
-
```
|
|
77
|
-
|
|
78
|
-
**Note:** To disable the module, set the environment variable `OASTLM_MODULE_DISABLED` to `'true'`.
|
|
79
|
-
|
|
80
|
-
## Telemetry UI
|
|
81
|
-
|
|
82
|
-
You can access the telemetry UI in the endpoint `/telemetry` (or `/custom-telemetry` if you set the `baseURL` option). This UI provides a user-friendly interface to interact with the telemetry data collected by the middleware.
|
|
83
|
-
|
|
84
|
-
## Metrics Development (Temporary)
|
|
85
|
-
|
|
86
|
-
This feature is currently in development. The following endpoints are available under <baseURL>/metrics (e.g., /telemetry/metrics):
|
|
87
|
-
|
|
88
|
-
- GET /
|
|
89
|
-
- POST /find
|
|
90
|
-
- GET /reset
|
|
91
|
-
|
|
92
|
-
Expect an array of metrics objects. Each object includes data like a timestamp, cpuUsageData, processCpuUsageData, memoryData, and processMemoryData. Example snippet for one CPU core (followed by others in the array):
|
|
93
|
-
|
|
94
|
-
```json
|
|
95
|
-
{
|
|
96
|
-
"timestamp": 1741717005911,
|
|
97
|
-
"cpuUsageData": [
|
|
98
|
-
{
|
|
99
|
-
"cpuNumber": "0",
|
|
100
|
-
"idle": 60486.234000000004,
|
|
101
|
-
"user": 1364.515,
|
|
102
|
-
"system": 1246.796,
|
|
103
|
-
"interrupt": 167,
|
|
104
|
-
"nice": 0,
|
|
105
|
-
"userP": 0.009375623379214043,
|
|
106
|
-
"systemP": 0.002992220227408737,
|
|
107
|
-
"idleP": 0.9850388988629563,
|
|
108
|
-
"interruptP": 0,
|
|
109
|
-
"niceP": 0
|
|
110
|
-
}
|
|
111
|
-
],
|
|
112
|
-
"processCpuUsageData": {
|
|
113
|
-
"user": 0.968,
|
|
114
|
-
"system": 0.32799999999999996,
|
|
115
|
-
"userP": 0,
|
|
116
|
-
"systemP": 0
|
|
117
|
-
},
|
|
118
|
-
"memoryData": {
|
|
119
|
-
"used": 15726522368,
|
|
120
|
-
"free": 18437427200,
|
|
121
|
-
"usedP": 0.4603250668280579,
|
|
122
|
-
"freeP": 0.539674933171942
|
|
123
|
-
},
|
|
124
|
-
"processMemoryData": 75988992,
|
|
125
|
-
"_id": "6mXKM8uK7xSOqJVT"
|
|
126
|
-
}
|
|
127
|
-
```
|
|
128
|
-
|
|
129
|
-
The shape of these objects may change as development continues.
|
|
130
|
-
|
|
131
|
-
## API Telemetry Endpoints
|
|
132
|
-
|
|
133
|
-
OAS Telemetry middleware adds the following endpoints to your Express application:
|
|
134
|
-
|
|
135
|
-
- /telemetry/start: Start telemetry data collection.
|
|
136
|
-
- /telemetry/stop: Stop telemetry data collection.
|
|
137
|
-
- /telemetry/status: Get status of telemetry.
|
|
138
|
-
- /telemetry/reset: Reset telemetry data.
|
|
139
|
-
- /telemetry/list: List all telemetry data.
|
|
140
|
-
- /telemetry/find (POST): Search telemetry data.
|
|
141
|
-
- /telemetry/heapStats: Shows v8 heapStats.
|
|
142
|
-
- /telemetry/plugins: List all plugins.
|
|
143
|
-
- /telemetry/plugins (POST): Add a plugin.
|
|
144
|
-
|
|
145
|
-
## Telemetry Plugins
|
|
146
|
-
|
|
147
|
-
OAS Telemetry supports a range of plugins to extend its functionality, allowing developers to tailor telemetry data collection, alerting, and reporting to meet specific requirements. Plugins enable additional features, such as integration with alerting systems, custom data exporters, and data visualization tools.
|
|
148
|
-
|
|
149
|
-
One example plugin is the **Outlier Alert Over Messaging** plugin, which can be configured to send anomaly alerts to messaging platforms like Telegram. This plugin is especially useful for monitoring abnormal response times in your API, notifying selected channels to allow rapid responses to potential issues. For setup details, refer to its [README documentation](https://github.com/oas-tools/oas-telemetry-plugin-outlier-messaging/blob/main/README.md).
|
|
150
|
-
|
|
151
|
-
OAS Telemetry plugins are flexible and support both ES Modules (ESM) and CommonJS (CJS) formats, regardless of whether your application is using ESM or CJS. This compatibility ensures that plugins work seamlessly in all configurations:
|
|
152
|
-
|
|
153
|
-
- ESM applications can use plugins in either ESM or CJS format.
|
|
154
|
-
- CJS applications can use plugins in either CJS or ESM format.
|
|
155
|
-
|
|
156
|
-
This flexibility makes it easy to incorporate a wide variety of plugins in your preferred module system.
|
|
157
|
-
|
|
158
|
-
## Accessing Telemetry Data
|
|
159
|
-
|
|
160
|
-
Using OAS Telemetry, you can access telemetry data through the UI, the `/telemetry/list` endpoint, or the `/telemetry/find` endpoint with a POST request using a MongoDB search syntax.
|
|
161
|
-
|
|
162
|
-
Note: if authentication is enabled, you must provide the correct credentials to access the telemetry data.
|
|
163
|
-
|
|
164
|
-
### Simple Search Example
|
|
165
|
-
|
|
166
|
-
To perform a simple search, send a POST request to the `/telemetry/find` endpoint with the following JSON payload:
|
|
167
|
-
|
|
168
|
-
```json
|
|
169
|
-
{
|
|
170
|
-
"search": {
|
|
171
|
-
"attributes.http.target": "/api/v1/pets",
|
|
172
|
-
"attributes.http.method": "GET",
|
|
173
|
-
"$or": [
|
|
174
|
-
{"attributes.http.status_code": 200},
|
|
175
|
-
{"attributes.http.status_code": 304}
|
|
176
|
-
]
|
|
177
|
-
}
|
|
178
|
-
}
|
|
179
|
-
```
|
|
180
|
-
|
|
181
|
-
### Complex Search Example
|
|
182
|
-
|
|
183
|
-
For more complex searches using regex, additional parsing on the server and extra attributes in the POST request are required. Send a POST request to the `/telemetry/find` endpoint with the following JSON payload:
|
|
184
|
-
|
|
185
|
-
```json
|
|
186
|
-
{
|
|
187
|
-
"flags": {
|
|
188
|
-
"containsRegex": true
|
|
189
|
-
},
|
|
190
|
-
"config": {
|
|
191
|
-
"regexIds": ["attributes.http.target"]
|
|
192
|
-
},
|
|
193
|
-
"search": {
|
|
194
|
-
"attributes.http.target": "^/api/v1/pets.*$",
|
|
195
|
-
"attributes.http.method": "GET",
|
|
196
|
-
"$or": [
|
|
197
|
-
{"attributes.http.status_code": 200},
|
|
198
|
-
{"attributes.http.status_code": 304}
|
|
199
|
-
]
|
|
200
|
-
}
|
|
201
|
-
}
|
|
202
|
-
```
|
|
203
|
-
|
|
204
|
-
## Full Examples
|
|
205
|
-
|
|
206
|
-
To run these examples, follow these steps:
|
|
207
|
-
|
|
208
|
-
1. Create a new folder for your project.
|
|
209
|
-
2. Navigate to the folder and initialize a new Node.js project:
|
|
210
|
-
|
|
211
|
-
```sh
|
|
212
|
-
npm init -y
|
|
213
|
-
```
|
|
214
|
-
|
|
215
|
-
3. Install the **OAS Telemetry** package:
|
|
216
|
-
|
|
217
|
-
```sh
|
|
218
|
-
npm install @oas-tools/oas-telemetry
|
|
219
|
-
```
|
|
220
|
-
|
|
221
|
-
4. Save the example code as `index.js` in the project folder.
|
|
222
|
-
5. Run the application:
|
|
223
|
-
|
|
224
|
-
```sh
|
|
225
|
-
node index.js
|
|
226
|
-
```
|
|
227
|
-
|
|
228
|
-
Your project folder should now contain the necessary files to run the example with **OAS Telemetry** integrated.
|
|
229
|
-
|
|
230
|
-
### Simple Example [ES Module](https://nodejs.org/docs/latest/api/esm.html) (*.mjs)
|
|
231
|
-
|
|
232
|
-
```js index.mjs
|
|
233
|
-
import oasTelemetry from '@oas-tools/oas-telemetry';
|
|
234
|
-
import express from 'express';
|
|
235
|
-
|
|
236
|
-
const app = express();
|
|
237
|
-
const port = 3000;
|
|
238
|
-
|
|
239
|
-
const spec = { "paths": {
|
|
240
|
-
"/api/v1/pets": {
|
|
241
|
-
"get": {
|
|
242
|
-
"summary": "Get pets",
|
|
243
|
-
"responses":{
|
|
244
|
-
"200": {
|
|
245
|
-
"description": "Success"
|
|
246
|
-
}
|
|
247
|
-
}
|
|
248
|
-
},
|
|
249
|
-
"post": {
|
|
250
|
-
"summary": "Insert a pet",
|
|
251
|
-
"responses":{
|
|
252
|
-
"201": {
|
|
253
|
-
"description": "Pet Created"
|
|
254
|
-
},
|
|
255
|
-
"400": {
|
|
256
|
-
"description": "Bad Request"
|
|
257
|
-
}
|
|
258
|
-
}
|
|
259
|
-
}
|
|
260
|
-
},
|
|
261
|
-
"/api/v1/pets/{petName}": {
|
|
262
|
-
"get": {
|
|
263
|
-
"summary": "Get a pet",
|
|
264
|
-
"parameters": [
|
|
265
|
-
{
|
|
266
|
-
"name": "petName",
|
|
267
|
-
"in": "path",
|
|
268
|
-
"required": true,
|
|
269
|
-
"description": "The name of the pet to retrieve",
|
|
270
|
-
"schema": {
|
|
271
|
-
"type": "string"
|
|
272
|
-
}
|
|
273
|
-
}
|
|
274
|
-
],
|
|
275
|
-
"responses":{
|
|
276
|
-
"200": {
|
|
277
|
-
"description": "Success"
|
|
278
|
-
},
|
|
279
|
-
"404": {
|
|
280
|
-
"description": "Not Found"
|
|
281
|
-
}
|
|
282
|
-
}
|
|
283
|
-
}
|
|
284
|
-
},
|
|
285
|
-
"/api/v1/clinics": {
|
|
286
|
-
"get": {
|
|
287
|
-
"summary": "Get pets",
|
|
288
|
-
"responses":{
|
|
289
|
-
"200": {
|
|
290
|
-
"description": "Success"
|
|
291
|
-
}
|
|
292
|
-
}
|
|
293
|
-
}
|
|
294
|
-
}
|
|
295
|
-
}
|
|
296
|
-
}
|
|
297
|
-
|
|
298
|
-
const oasTlmConfig = {
|
|
299
|
-
spec : JSON.stringify(spec),
|
|
300
|
-
baseURL: "/telemetry",
|
|
301
|
-
}
|
|
302
|
-
app.use(oasTelemetry(oasTlmConfig));
|
|
303
|
-
|
|
304
|
-
app.use(express.json());
|
|
305
|
-
|
|
306
|
-
app.listen(port, () => {
|
|
307
|
-
console.log(`Example app listening at http://localhost:${port}`);
|
|
308
|
-
console.log(`Telemetry portal available at http://localhost:${port}${oasTlmConfig.baseURL}`);
|
|
309
|
-
});
|
|
310
|
-
|
|
311
|
-
let pets =[{ name: "rocky"},{ name: "pikachu"}];
|
|
312
|
-
let clinics =[{ name: "Pet Heaven"},{ name: "Pet Care"}];
|
|
313
|
-
|
|
314
|
-
app.get("/api/v1/pets", (req, res) => {
|
|
315
|
-
res.send(pets);
|
|
316
|
-
});
|
|
317
|
-
app.post("/api/v1/pets", (req, res) => {
|
|
318
|
-
if(req.body && req.body.name){
|
|
319
|
-
pets.push(req.body);
|
|
320
|
-
res.sendStatus(201);
|
|
321
|
-
}else{
|
|
322
|
-
res.sendStatus(400);
|
|
323
|
-
}
|
|
324
|
-
});
|
|
325
|
-
app.get("/api/v1/pets/:name", (req, res) => {
|
|
326
|
-
let name = req.params.name;
|
|
327
|
-
let filterdPets = pets.filter((p)=>(p.name==name));
|
|
328
|
-
if(filterdPets.length > 0)
|
|
329
|
-
return res.send(filterdPets[0]);
|
|
330
|
-
else
|
|
331
|
-
return res.sendStatus(404);
|
|
332
|
-
});
|
|
333
|
-
app.get("/api/v1/clinics", (req, res) => {
|
|
334
|
-
res.send(clinics);
|
|
335
|
-
});
|
|
336
|
-
```
|
|
337
|
-
|
|
338
|
-
### Simple Example [Common.js Module](https://nodejs.org/docs/latest/api/modules.html) (*.cjs)
|
|
339
|
-
|
|
340
|
-
```js index.cjs
|
|
341
|
-
let oasTelemetry = require('@oas-tools/oas-telemetry');
|
|
342
|
-
let express = require('express');
|
|
343
|
-
|
|
344
|
-
const app = express();
|
|
345
|
-
const port = 3000;
|
|
346
|
-
|
|
347
|
-
const spec = { "paths": {
|
|
348
|
-
"/api/v1/pets": {
|
|
349
|
-
"get": {
|
|
350
|
-
"summary": "Get pets",
|
|
351
|
-
"responses":{
|
|
352
|
-
"200": {
|
|
353
|
-
"description": "Success"
|
|
354
|
-
}
|
|
355
|
-
}
|
|
356
|
-
},
|
|
357
|
-
"post": {
|
|
358
|
-
"summary": "Insert a pet",
|
|
359
|
-
"responses":{
|
|
360
|
-
"201": {
|
|
361
|
-
"description": "Pet Created"
|
|
362
|
-
},
|
|
363
|
-
"400": {
|
|
364
|
-
"description": "Bad Request"
|
|
365
|
-
}
|
|
366
|
-
}
|
|
367
|
-
}
|
|
368
|
-
},
|
|
369
|
-
"/api/v1/pets/{petName}": {
|
|
370
|
-
"get": {
|
|
371
|
-
"summary": "Get a pet",
|
|
372
|
-
"parameters": [
|
|
373
|
-
{
|
|
374
|
-
"name": "petName",
|
|
375
|
-
"in": "path",
|
|
376
|
-
"required": true,
|
|
377
|
-
"description": "The name of the pet to retrieve",
|
|
378
|
-
"schema": {
|
|
379
|
-
"type": "string"
|
|
380
|
-
}
|
|
381
|
-
}
|
|
382
|
-
],
|
|
383
|
-
"responses":{
|
|
384
|
-
"200": {
|
|
385
|
-
"description": "Success"
|
|
386
|
-
},
|
|
387
|
-
"404": {
|
|
388
|
-
"description": "Not Found"
|
|
389
|
-
}
|
|
390
|
-
}
|
|
391
|
-
}
|
|
392
|
-
},
|
|
393
|
-
"/api/v1/clinics": {
|
|
394
|
-
"get": {
|
|
395
|
-
"summary": "Get pets",
|
|
396
|
-
"responses":{
|
|
397
|
-
"200": {
|
|
398
|
-
"description": "Success"
|
|
399
|
-
}
|
|
400
|
-
}
|
|
401
|
-
}
|
|
402
|
-
}
|
|
403
|
-
}
|
|
404
|
-
}
|
|
405
|
-
|
|
406
|
-
app.use(oasTelemetry({
|
|
407
|
-
spec : JSON.stringify(spec)
|
|
408
|
-
}))
|
|
409
|
-
|
|
410
|
-
app.use(express.json());
|
|
411
|
-
|
|
412
|
-
app.listen(port, () => {
|
|
413
|
-
console.log(`Example app listening at http://localhost:${port}`);
|
|
414
|
-
console.log(`Telemetry portal available at http://localhost:${port}/telemetry`);
|
|
415
|
-
});
|
|
416
|
-
|
|
417
|
-
let pets =[{ name: "rocky"},{ name: "pikachu"}];
|
|
418
|
-
let clinics =[{ name: "Pet Heaven"},{ name: "Pet Care"}];
|
|
419
|
-
|
|
420
|
-
app.get("/api/v1/pets", (req, res) => {
|
|
421
|
-
res.send(pets);
|
|
422
|
-
});
|
|
423
|
-
app.post("/api/v1/pets", (req, res) => {
|
|
424
|
-
if(req.body && req.body.name){
|
|
425
|
-
pets.push(req.body);
|
|
426
|
-
res.sendStatus(201);
|
|
427
|
-
}else{
|
|
428
|
-
res.sendStatus(400);
|
|
429
|
-
}
|
|
430
|
-
});
|
|
431
|
-
app.get("/api/v1/pets/:name", (req, res) => {
|
|
432
|
-
let name = req.params.name;
|
|
433
|
-
let filterdPets = pets.filter((p)=>(p.name==name));
|
|
434
|
-
if(filterdPets.length > 0)
|
|
435
|
-
return res.send(filterdPets[0]);
|
|
436
|
-
else
|
|
437
|
-
return res.sendStatus(404);
|
|
438
|
-
});
|
|
439
|
-
app.get("/api/v1/clinics", (req, res) => {
|
|
440
|
-
res.send(clinics);
|
|
441
|
-
});
|
|
442
|
-
```
|
|
1
|
+
# OAS TELEMETRY
|
|
2
|
+
|
|
3
|
+
**OAS Telemetry** offers an express middleware designed for collecting telemetry data using **Open Telemetry** in applications built using the **OpenAPI Specification (OAS)**. This middleware allows developers to easily incorporate telemetry functionality into their APIs.
|
|
4
|
+
|
|
5
|
+
**OAS Telemetry** provides a set of endpoints that can be accessed to perform various actions related to telemetry data, such as starting and stopping data collection, resetting telemetry data, listing collected data, and searching for specific telemetry records. These endpoints can be easily integrated into an **Express.js** application, providing developers with a convenient way to manage and analyze telemetry data.
|
|
6
|
+
|
|
7
|
+
Additionally, **OAS Telemetry** offers customization options, allowing developers to configure the telemetry middleware according to their specific requirements.
|
|
8
|
+
|
|
9
|
+
Overall, **OAS Telemetry** will serve as a valuable tool for developers looking to gain insights into the operation and performance of their **OAS-based APIs**, enabling them to monitor, debug, and optimize their applications effectively.
|
|
10
|
+
|
|
11
|
+
The package now supports both **ES Module (ESM)** and **CommonJS (CJS)** formats, making it compatible with a wide range of applications. The ESM build targets the **ES2020** standard. Furthermore, **OAS Telemetry** provides a range of plugins to extend its functionality. See the [Telemetry Plugins](#telemetry-plugins) section for more information.
|
|
12
|
+
|
|
13
|
+
## Usage
|
|
14
|
+
|
|
15
|
+
This section provides an overview of how to install and integrate **OAS Telemetry** into your EXISTING **Express.js** application. If you want to create a new example express application with **OAS Telemetry** integrated, refer to the [Full Examples](#full-examples) section at the end of this document.
|
|
16
|
+
|
|
17
|
+
First, install the package using npm:
|
|
18
|
+
|
|
19
|
+
```sh
|
|
20
|
+
npm install @oas-tools/oas-telemetry
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
You can integrate the middleware into your Express application. The `spec` option is the OpenAPI Specification (OAS) content in JSON or YAML format. While this configuration is optional, it is recommended for the UI to function correctly.
|
|
24
|
+
|
|
25
|
+
### Using ES Modules (ESM)
|
|
26
|
+
|
|
27
|
+
Add the following lines to your `index.js` file:
|
|
28
|
+
|
|
29
|
+
```js
|
|
30
|
+
// This import MUST be at the top of the file
|
|
31
|
+
import oasTelemetry from '@oas-tools/oas-telemetry';
|
|
32
|
+
import { readFileSync } from 'fs';
|
|
33
|
+
|
|
34
|
+
// ...rest of your code here creating an express app
|
|
35
|
+
|
|
36
|
+
app.use(oasTelemetry({
|
|
37
|
+
spec: readFileSync('./spec/oas.yaml', { encoding: 'utf8', flag: 'r' })
|
|
38
|
+
}));
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
### Using CommonJS
|
|
42
|
+
|
|
43
|
+
Add the following lines to your `index.js` file:
|
|
44
|
+
|
|
45
|
+
```js
|
|
46
|
+
// This require MUST be at the top of the file
|
|
47
|
+
const oasTelemetry = require('@oas-tools/oas-telemetry');
|
|
48
|
+
const { readFileSync } = require('fs');
|
|
49
|
+
|
|
50
|
+
// ...rest of your code here creating an express app
|
|
51
|
+
|
|
52
|
+
app.use(oasTelemetry({
|
|
53
|
+
spec: readFileSync('./spec/oas.yaml', { encoding: 'utf8', flag: 'r' })
|
|
54
|
+
}));
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
For complete examples of a working API with OAS Telemetry enabled, refer to the [Full Examples](#full-examples) section at the end of this document.
|
|
58
|
+
|
|
59
|
+
## Custom Configuration
|
|
60
|
+
|
|
61
|
+
You can also customize the telemetry configuration by passing options to the middleware function. For example:
|
|
62
|
+
|
|
63
|
+
```js
|
|
64
|
+
const customTelemetryConfig = {
|
|
65
|
+
spec: /* OAS content in json or yaml */, // Highly recommended
|
|
66
|
+
baseURL: "/custom-telemetry", //default is "/telemetry"
|
|
67
|
+
autoActivate: false, //default is true, whether to start telemetry data collection automatically
|
|
68
|
+
authEnabled: true, //default is false
|
|
69
|
+
apiKeyMaxAge: 1000 * 60 * 30, // 30 minutes
|
|
70
|
+
password: "custom-password", //default is "oas-telemetry-password"
|
|
71
|
+
jwtSecret: "custom-secret", //default is "oas-telemetry-secret"
|
|
72
|
+
exporter: myCustomExporter, // Experimental, just for devs
|
|
73
|
+
};
|
|
74
|
+
|
|
75
|
+
app.use(oasTelemetry(customTelemetryConfig));
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
**Note:** To disable the module, set the environment variable `OASTLM_MODULE_DISABLED` to `'true'`.
|
|
79
|
+
|
|
80
|
+
## Telemetry UI
|
|
81
|
+
|
|
82
|
+
You can access the telemetry UI in the endpoint `/telemetry` (or `/custom-telemetry` if you set the `baseURL` option). This UI provides a user-friendly interface to interact with the telemetry data collected by the middleware.
|
|
83
|
+
|
|
84
|
+
## Metrics Development (Temporary)
|
|
85
|
+
|
|
86
|
+
This feature is currently in development. The following endpoints are available under <baseURL>/metrics (e.g., /telemetry/metrics):
|
|
87
|
+
|
|
88
|
+
- GET /
|
|
89
|
+
- POST /find
|
|
90
|
+
- GET /reset
|
|
91
|
+
|
|
92
|
+
Expect an array of metrics objects. Each object includes data like a timestamp, cpuUsageData, processCpuUsageData, memoryData, and processMemoryData. Example snippet for one CPU core (followed by others in the array):
|
|
93
|
+
|
|
94
|
+
```json
|
|
95
|
+
{
|
|
96
|
+
"timestamp": 1741717005911,
|
|
97
|
+
"cpuUsageData": [
|
|
98
|
+
{
|
|
99
|
+
"cpuNumber": "0",
|
|
100
|
+
"idle": 60486.234000000004,
|
|
101
|
+
"user": 1364.515,
|
|
102
|
+
"system": 1246.796,
|
|
103
|
+
"interrupt": 167,
|
|
104
|
+
"nice": 0,
|
|
105
|
+
"userP": 0.009375623379214043,
|
|
106
|
+
"systemP": 0.002992220227408737,
|
|
107
|
+
"idleP": 0.9850388988629563,
|
|
108
|
+
"interruptP": 0,
|
|
109
|
+
"niceP": 0
|
|
110
|
+
}
|
|
111
|
+
],
|
|
112
|
+
"processCpuUsageData": {
|
|
113
|
+
"user": 0.968,
|
|
114
|
+
"system": 0.32799999999999996,
|
|
115
|
+
"userP": 0,
|
|
116
|
+
"systemP": 0
|
|
117
|
+
},
|
|
118
|
+
"memoryData": {
|
|
119
|
+
"used": 15726522368,
|
|
120
|
+
"free": 18437427200,
|
|
121
|
+
"usedP": 0.4603250668280579,
|
|
122
|
+
"freeP": 0.539674933171942
|
|
123
|
+
},
|
|
124
|
+
"processMemoryData": 75988992,
|
|
125
|
+
"_id": "6mXKM8uK7xSOqJVT"
|
|
126
|
+
}
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
The shape of these objects may change as development continues.
|
|
130
|
+
|
|
131
|
+
## API Telemetry Endpoints
|
|
132
|
+
|
|
133
|
+
OAS Telemetry middleware adds the following endpoints to your Express application:
|
|
134
|
+
|
|
135
|
+
- /telemetry/start: Start telemetry data collection.
|
|
136
|
+
- /telemetry/stop: Stop telemetry data collection.
|
|
137
|
+
- /telemetry/status: Get status of telemetry.
|
|
138
|
+
- /telemetry/reset: Reset telemetry data.
|
|
139
|
+
- /telemetry/list: List all telemetry data.
|
|
140
|
+
- /telemetry/find (POST): Search telemetry data.
|
|
141
|
+
- /telemetry/heapStats: Shows v8 heapStats.
|
|
142
|
+
- /telemetry/plugins: List all plugins.
|
|
143
|
+
- /telemetry/plugins (POST): Add a plugin.
|
|
144
|
+
|
|
145
|
+
## Telemetry Plugins
|
|
146
|
+
|
|
147
|
+
OAS Telemetry supports a range of plugins to extend its functionality, allowing developers to tailor telemetry data collection, alerting, and reporting to meet specific requirements. Plugins enable additional features, such as integration with alerting systems, custom data exporters, and data visualization tools.
|
|
148
|
+
|
|
149
|
+
One example plugin is the **Outlier Alert Over Messaging** plugin, which can be configured to send anomaly alerts to messaging platforms like Telegram. This plugin is especially useful for monitoring abnormal response times in your API, notifying selected channels to allow rapid responses to potential issues. For setup details, refer to its [README documentation](https://github.com/oas-tools/oas-telemetry-plugin-outlier-messaging/blob/main/README.md).
|
|
150
|
+
|
|
151
|
+
OAS Telemetry plugins are flexible and support both ES Modules (ESM) and CommonJS (CJS) formats, regardless of whether your application is using ESM or CJS. This compatibility ensures that plugins work seamlessly in all configurations:
|
|
152
|
+
|
|
153
|
+
- ESM applications can use plugins in either ESM or CJS format.
|
|
154
|
+
- CJS applications can use plugins in either CJS or ESM format.
|
|
155
|
+
|
|
156
|
+
This flexibility makes it easy to incorporate a wide variety of plugins in your preferred module system.
|
|
157
|
+
|
|
158
|
+
## Accessing Telemetry Data
|
|
159
|
+
|
|
160
|
+
Using OAS Telemetry, you can access telemetry data through the UI, the `/telemetry/list` endpoint, or the `/telemetry/find` endpoint with a POST request using a MongoDB search syntax.
|
|
161
|
+
|
|
162
|
+
Note: if authentication is enabled, you must provide the correct credentials to access the telemetry data.
|
|
163
|
+
|
|
164
|
+
### Simple Search Example
|
|
165
|
+
|
|
166
|
+
To perform a simple search, send a POST request to the `/telemetry/find` endpoint with the following JSON payload:
|
|
167
|
+
|
|
168
|
+
```json
|
|
169
|
+
{
|
|
170
|
+
"search": {
|
|
171
|
+
"attributes.http.target": "/api/v1/pets",
|
|
172
|
+
"attributes.http.method": "GET",
|
|
173
|
+
"$or": [
|
|
174
|
+
{"attributes.http.status_code": 200},
|
|
175
|
+
{"attributes.http.status_code": 304}
|
|
176
|
+
]
|
|
177
|
+
}
|
|
178
|
+
}
|
|
179
|
+
```
|
|
180
|
+
|
|
181
|
+
### Complex Search Example
|
|
182
|
+
|
|
183
|
+
For more complex searches using regex, additional parsing on the server and extra attributes in the POST request are required. Send a POST request to the `/telemetry/find` endpoint with the following JSON payload:
|
|
184
|
+
|
|
185
|
+
```json
|
|
186
|
+
{
|
|
187
|
+
"flags": {
|
|
188
|
+
"containsRegex": true
|
|
189
|
+
},
|
|
190
|
+
"config": {
|
|
191
|
+
"regexIds": ["attributes.http.target"]
|
|
192
|
+
},
|
|
193
|
+
"search": {
|
|
194
|
+
"attributes.http.target": "^/api/v1/pets.*$",
|
|
195
|
+
"attributes.http.method": "GET",
|
|
196
|
+
"$or": [
|
|
197
|
+
{"attributes.http.status_code": 200},
|
|
198
|
+
{"attributes.http.status_code": 304}
|
|
199
|
+
]
|
|
200
|
+
}
|
|
201
|
+
}
|
|
202
|
+
```
|
|
203
|
+
|
|
204
|
+
## Full Examples
|
|
205
|
+
|
|
206
|
+
To run these examples, follow these steps:
|
|
207
|
+
|
|
208
|
+
1. Create a new folder for your project.
|
|
209
|
+
2. Navigate to the folder and initialize a new Node.js project:
|
|
210
|
+
|
|
211
|
+
```sh
|
|
212
|
+
npm init -y
|
|
213
|
+
```
|
|
214
|
+
|
|
215
|
+
3. Install the **OAS Telemetry** package:
|
|
216
|
+
|
|
217
|
+
```sh
|
|
218
|
+
npm install @oas-tools/oas-telemetry
|
|
219
|
+
```
|
|
220
|
+
|
|
221
|
+
4. Save the example code as `index.js` in the project folder.
|
|
222
|
+
5. Run the application:
|
|
223
|
+
|
|
224
|
+
```sh
|
|
225
|
+
node index.js
|
|
226
|
+
```
|
|
227
|
+
|
|
228
|
+
Your project folder should now contain the necessary files to run the example with **OAS Telemetry** integrated.
|
|
229
|
+
|
|
230
|
+
### Simple Example [ES Module](https://nodejs.org/docs/latest/api/esm.html) (*.mjs)
|
|
231
|
+
|
|
232
|
+
```js index.mjs
|
|
233
|
+
import oasTelemetry from '@oas-tools/oas-telemetry';
|
|
234
|
+
import express from 'express';
|
|
235
|
+
|
|
236
|
+
const app = express();
|
|
237
|
+
const port = 3000;
|
|
238
|
+
|
|
239
|
+
const spec = { "paths": {
|
|
240
|
+
"/api/v1/pets": {
|
|
241
|
+
"get": {
|
|
242
|
+
"summary": "Get pets",
|
|
243
|
+
"responses":{
|
|
244
|
+
"200": {
|
|
245
|
+
"description": "Success"
|
|
246
|
+
}
|
|
247
|
+
}
|
|
248
|
+
},
|
|
249
|
+
"post": {
|
|
250
|
+
"summary": "Insert a pet",
|
|
251
|
+
"responses":{
|
|
252
|
+
"201": {
|
|
253
|
+
"description": "Pet Created"
|
|
254
|
+
},
|
|
255
|
+
"400": {
|
|
256
|
+
"description": "Bad Request"
|
|
257
|
+
}
|
|
258
|
+
}
|
|
259
|
+
}
|
|
260
|
+
},
|
|
261
|
+
"/api/v1/pets/{petName}": {
|
|
262
|
+
"get": {
|
|
263
|
+
"summary": "Get a pet",
|
|
264
|
+
"parameters": [
|
|
265
|
+
{
|
|
266
|
+
"name": "petName",
|
|
267
|
+
"in": "path",
|
|
268
|
+
"required": true,
|
|
269
|
+
"description": "The name of the pet to retrieve",
|
|
270
|
+
"schema": {
|
|
271
|
+
"type": "string"
|
|
272
|
+
}
|
|
273
|
+
}
|
|
274
|
+
],
|
|
275
|
+
"responses":{
|
|
276
|
+
"200": {
|
|
277
|
+
"description": "Success"
|
|
278
|
+
},
|
|
279
|
+
"404": {
|
|
280
|
+
"description": "Not Found"
|
|
281
|
+
}
|
|
282
|
+
}
|
|
283
|
+
}
|
|
284
|
+
},
|
|
285
|
+
"/api/v1/clinics": {
|
|
286
|
+
"get": {
|
|
287
|
+
"summary": "Get pets",
|
|
288
|
+
"responses":{
|
|
289
|
+
"200": {
|
|
290
|
+
"description": "Success"
|
|
291
|
+
}
|
|
292
|
+
}
|
|
293
|
+
}
|
|
294
|
+
}
|
|
295
|
+
}
|
|
296
|
+
}
|
|
297
|
+
|
|
298
|
+
const oasTlmConfig = {
|
|
299
|
+
spec : JSON.stringify(spec),
|
|
300
|
+
baseURL: "/telemetry",
|
|
301
|
+
}
|
|
302
|
+
app.use(oasTelemetry(oasTlmConfig));
|
|
303
|
+
|
|
304
|
+
app.use(express.json());
|
|
305
|
+
|
|
306
|
+
app.listen(port, () => {
|
|
307
|
+
console.log(`Example app listening at http://localhost:${port}`);
|
|
308
|
+
console.log(`Telemetry portal available at http://localhost:${port}${oasTlmConfig.baseURL}`);
|
|
309
|
+
});
|
|
310
|
+
|
|
311
|
+
let pets =[{ name: "rocky"},{ name: "pikachu"}];
|
|
312
|
+
let clinics =[{ name: "Pet Heaven"},{ name: "Pet Care"}];
|
|
313
|
+
|
|
314
|
+
app.get("/api/v1/pets", (req, res) => {
|
|
315
|
+
res.send(pets);
|
|
316
|
+
});
|
|
317
|
+
app.post("/api/v1/pets", (req, res) => {
|
|
318
|
+
if(req.body && req.body.name){
|
|
319
|
+
pets.push(req.body);
|
|
320
|
+
res.sendStatus(201);
|
|
321
|
+
}else{
|
|
322
|
+
res.sendStatus(400);
|
|
323
|
+
}
|
|
324
|
+
});
|
|
325
|
+
app.get("/api/v1/pets/:name", (req, res) => {
|
|
326
|
+
let name = req.params.name;
|
|
327
|
+
let filterdPets = pets.filter((p)=>(p.name==name));
|
|
328
|
+
if(filterdPets.length > 0)
|
|
329
|
+
return res.send(filterdPets[0]);
|
|
330
|
+
else
|
|
331
|
+
return res.sendStatus(404);
|
|
332
|
+
});
|
|
333
|
+
app.get("/api/v1/clinics", (req, res) => {
|
|
334
|
+
res.send(clinics);
|
|
335
|
+
});
|
|
336
|
+
```
|
|
337
|
+
|
|
338
|
+
### Simple Example [Common.js Module](https://nodejs.org/docs/latest/api/modules.html) (*.cjs)
|
|
339
|
+
|
|
340
|
+
```js index.cjs
|
|
341
|
+
let oasTelemetry = require('@oas-tools/oas-telemetry');
|
|
342
|
+
let express = require('express');
|
|
343
|
+
|
|
344
|
+
const app = express();
|
|
345
|
+
const port = 3000;
|
|
346
|
+
|
|
347
|
+
const spec = { "paths": {
|
|
348
|
+
"/api/v1/pets": {
|
|
349
|
+
"get": {
|
|
350
|
+
"summary": "Get pets",
|
|
351
|
+
"responses":{
|
|
352
|
+
"200": {
|
|
353
|
+
"description": "Success"
|
|
354
|
+
}
|
|
355
|
+
}
|
|
356
|
+
},
|
|
357
|
+
"post": {
|
|
358
|
+
"summary": "Insert a pet",
|
|
359
|
+
"responses":{
|
|
360
|
+
"201": {
|
|
361
|
+
"description": "Pet Created"
|
|
362
|
+
},
|
|
363
|
+
"400": {
|
|
364
|
+
"description": "Bad Request"
|
|
365
|
+
}
|
|
366
|
+
}
|
|
367
|
+
}
|
|
368
|
+
},
|
|
369
|
+
"/api/v1/pets/{petName}": {
|
|
370
|
+
"get": {
|
|
371
|
+
"summary": "Get a pet",
|
|
372
|
+
"parameters": [
|
|
373
|
+
{
|
|
374
|
+
"name": "petName",
|
|
375
|
+
"in": "path",
|
|
376
|
+
"required": true,
|
|
377
|
+
"description": "The name of the pet to retrieve",
|
|
378
|
+
"schema": {
|
|
379
|
+
"type": "string"
|
|
380
|
+
}
|
|
381
|
+
}
|
|
382
|
+
],
|
|
383
|
+
"responses":{
|
|
384
|
+
"200": {
|
|
385
|
+
"description": "Success"
|
|
386
|
+
},
|
|
387
|
+
"404": {
|
|
388
|
+
"description": "Not Found"
|
|
389
|
+
}
|
|
390
|
+
}
|
|
391
|
+
}
|
|
392
|
+
},
|
|
393
|
+
"/api/v1/clinics": {
|
|
394
|
+
"get": {
|
|
395
|
+
"summary": "Get pets",
|
|
396
|
+
"responses":{
|
|
397
|
+
"200": {
|
|
398
|
+
"description": "Success"
|
|
399
|
+
}
|
|
400
|
+
}
|
|
401
|
+
}
|
|
402
|
+
}
|
|
403
|
+
}
|
|
404
|
+
}
|
|
405
|
+
|
|
406
|
+
app.use(oasTelemetry({
|
|
407
|
+
spec : JSON.stringify(spec)
|
|
408
|
+
}))
|
|
409
|
+
|
|
410
|
+
app.use(express.json());
|
|
411
|
+
|
|
412
|
+
app.listen(port, () => {
|
|
413
|
+
console.log(`Example app listening at http://localhost:${port}`);
|
|
414
|
+
console.log(`Telemetry portal available at http://localhost:${port}/telemetry`);
|
|
415
|
+
});
|
|
416
|
+
|
|
417
|
+
let pets =[{ name: "rocky"},{ name: "pikachu"}];
|
|
418
|
+
let clinics =[{ name: "Pet Heaven"},{ name: "Pet Care"}];
|
|
419
|
+
|
|
420
|
+
app.get("/api/v1/pets", (req, res) => {
|
|
421
|
+
res.send(pets);
|
|
422
|
+
});
|
|
423
|
+
app.post("/api/v1/pets", (req, res) => {
|
|
424
|
+
if(req.body && req.body.name){
|
|
425
|
+
pets.push(req.body);
|
|
426
|
+
res.sendStatus(201);
|
|
427
|
+
}else{
|
|
428
|
+
res.sendStatus(400);
|
|
429
|
+
}
|
|
430
|
+
});
|
|
431
|
+
app.get("/api/v1/pets/:name", (req, res) => {
|
|
432
|
+
let name = req.params.name;
|
|
433
|
+
let filterdPets = pets.filter((p)=>(p.name==name));
|
|
434
|
+
if(filterdPets.length > 0)
|
|
435
|
+
return res.send(filterdPets[0]);
|
|
436
|
+
else
|
|
437
|
+
return res.sendStatus(404);
|
|
438
|
+
});
|
|
439
|
+
app.get("/api/v1/clinics", (req, res) => {
|
|
440
|
+
res.send(clinics);
|
|
441
|
+
});
|
|
442
|
+
```
|