|
1 | | -# Traceo SDK for Node.js |
2 | | -[](https://opensource.org/licenses/MIT) |
| 1 | +# Traceo SDKs for JavaScript |
3 | 2 |
|
4 | | -Library for integration with the [Traceo Platform](https://github.com/traceo-dev/traceo). |
| 3 | +A set of SDKS for integration with the [Traceo Platform](https://github.com/traceo-dev/traceo). |
5 | 4 |
|
6 | | -### Installation |
7 | | -To install this SDK add this package to your project like below: |
8 | | -``` |
9 | | -yarn add @traceo-sdk/node |
10 | | -``` |
11 | | -or |
12 | | -``` |
13 | | -npm install @traceo-sdk/node |
14 | | -``` |
| 5 | +# Platforms |
| 6 | +This repository contains all the SDKs needed for integration in Javascript/Typescript projects. Detailed instructions for the SDK implementation process can be found in the individual README for each SDK. |
15 | 7 |
|
16 | | -### Usage |
17 | | -First what you need is to initialize `TraceoClient` in your application. |
18 | | -```ts |
19 | | -import { TraceoClient } from "@traceo-sdk/node"; |
| 8 | +- [`@traceo-sdk/node`](https://github.com/traceo-dev/traceo-sdk/tree/develop/packages/node): SDK for NodeJS. |
| 9 | +- [`@traceo-sdk/react`](https://github.com/traceo-dev/traceo-sdk/tree/develop/packages/react): SDK for ReactJS. |
20 | 10 |
|
21 | | -new TraceoClient({ |
22 | | - appId: <your_application_id>, |
23 | | - apiKey: <app_api_key>, |
24 | | - url: <you_traceo_instance_url> |
25 | | -}); |
26 | | -``` |
27 | | - |
28 | | -`TraceoClient` require three parameters. `appId` is a unique identifier of an application created on the Traceo platform. Information about application ID you can get from the Traceo Platform in `Settings|Details` tab. In this same place you can get `apiKey`. `url` parameter specifies the address where your Traceo Platform instance is located. Address should be passed in the format `<protocol>://<domain>:<port>`, eq. `http://localhost:3000`. |
29 | | - |
30 | | -### Incidents handling |
31 | | -Incidents are all the exceptions and other problems that occur in your application. After each exception occurs, the Traceo SDK catches the exception and sends it to the Traceo Platform. This package provide the two main ways to catch exceptions in your application - `Handlers` and `Middlewares`. |
32 | | - |
33 | | -##### Handlers |
34 | | -The easiest way is to use `ExceptionsHandlers.catchException()` in `try-catch` clause like below: |
35 | | -```ts |
36 | | -import { ExceptionHandlers } from "@traceo-sdk/node"; |
37 | | - |
38 | | -try { |
39 | | - //your code |
40 | | -} catch (error) { |
41 | | - ExceptionHandlers.catchException(error); |
42 | | -} |
43 | | -``` |
44 | | - |
45 | | -If you use [NestJS](https://nestjs.com/) framework then you can also create [Interceptor](https://docs.nestjs.com/interceptors) to catch exceptions like below: |
46 | | - |
47 | | -traceo.interceptor.ts |
48 | | -```ts |
49 | | -import { ExceptionHandlers } from "@traceo-sdk/node"; |
50 | | -//other imports |
51 | | - |
52 | | -@Injectable() |
53 | | -export class TraceoInterceptor implements NestInterceptor { |
54 | | - intercept(context: ExecutionContext, next: CallHandler): Observable<any> { |
55 | | - return next.handle().pipe( |
56 | | - tap(null, (exception) => { |
57 | | - ExceptionHandlers.catchException(exception); |
58 | | - }), |
59 | | - ); |
60 | | - } |
61 | | -} |
62 | | -``` |
63 | | - |
64 | | -main.ts |
65 | | -```ts |
66 | | - app.useGlobalInterceptors(new TraceoInterceptor()); |
67 | | -``` |
68 | | - |
69 | | -##### Middleware |
70 | | -Another approach is to use `ExceptionMiddlewares.errorMiddleware()`. If you use the [Express.js](https://expressjs.com/) framework, you can use our middl# Traceo SDK for Node.js |
71 | | - |
72 | | -Javascript: |
73 | | -```js |
74 | | -import { ExceptionMiddlewares } from "@traceo-sdk/node"; |
75 | | - |
76 | | -app.use(ExceptionMiddlewares.errorMiddleware()); |
77 | | -``` |
78 | | - |
79 | | -Typescript: |
80 | | -```ts |
81 | | -const { ExceptionMiddlewares } from "@traceo-sdk/node"; |
82 | | - |
83 | | -app.use(ExceptionMiddlewares.errorMiddleware() as express.ErrorRequestHandler); |
84 | | -``` |
85 | | - |
86 | | -Remember that `ExceptionMiddlwares.errorMiddleware()` should be before any other error middlewares and after all routes/controllers. |
87 | | - |
88 | | -##### Middleware options |
89 | | - |
90 | | - |
91 | | -| Parameter | Description | Default | |
92 | | -| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | |
93 | | -| `allowLocalhost` | If false then middleware doesn't catch exceptions from requests coming from `localhost` | true | |
94 | | -| `allowHttp` | If false then middleware doesn't catch exceptions received from requests where `req.protocol = http` and catch only exception received with `https` | true | |
95 | | - |
96 | | -### Logger |
97 | | -The Traceo SDK can be used also as a logger. Each log is saved on the Traceo Platform, thanks to which it is possible to later easily access the recorded information. Logs are sent to Traceo in every 60 seconds. To change this behavior, set a custom value (measured in seconds) in the `scrapLogsInterval` field inside traceo client properties like below: |
98 | | -```ts |
99 | | -import { TraceoClient } from "@traceo-sdk/node"; |
100 | | - |
101 | | -new TraceoClient({ |
102 | | - scrapLogsInterval: 120 //in seconds |
103 | | -}); |
104 | | -``` |
105 | | - |
106 | | -Example of using logger: |
107 | | -```ts |
108 | | -import { Logger } from "@traceo-sdk/node"; |
109 | | - |
110 | | -const traceo = new TraceoClient({...}); |
111 | | - |
112 | | -traceo.logger.log("Traceo"); |
113 | | -``` |
114 | | - |
115 | | -The `logger` can use 5 different types of log: `log`, `info`, `debug`, `warn`, `error`. Each function responsible for logging the appropriate log type accepts a list of arguments in the parameter. |
116 | | -```ts |
117 | | -traceo.logger.log("Traceo", "Example", "Log"); |
118 | | -// [TraceoLogger][LOG] - 31.10.2022, 13:55:45 - Traceo Example Log |
119 | | - |
120 | | -traceo.logger.debug("Traceo", { |
121 | | - hello: "World" |
122 | | -}); |
123 | | -// [TraceoLogger][DEBUG] - 31.10.2022, 13:58:00 - Traceo { hello: 'World' } |
124 | | -``` |
125 | | -### Metrics |
126 | | -To activate the collection of metrics from your application, set the parameter `collectMetrics` in your `TraceoClient` to true: |
127 | | - |
128 | | -```ts |
129 | | -new TraceoClient({ collectMetrics: true }); |
130 | | -``` |
131 | | -Metrics are collected from the application every 30 seconds. If you want to collect metrics at a different time interval then you can use the `scrapMetricsInterval` parameter. |
132 | | - |
133 | | -```ts |
134 | | -new TraceoClient({ scrapMetricsInterval: <interval_in_seconds> }); |
135 | | -``` |
136 | | - |
137 | | -Remember that provided `scrapMetricsInterval` can't be less than `15` seconds. |
| 11 | +# Other |
| 12 | +- [`@traceo-sdk/browser`](https://github.com/traceo/traceo-sdk/tree/develop/packages/browser): A package that contains common logic used by all SDKs running in the browser. |
138 | 13 |
|
139 | 14 | ## Support |
140 | 15 | Feel free to create Issues, Pull Request and Discussion. If you want to contact with the developer working on this package click [here](mailto:piotr.szewczyk.software@gmail.com). |
141 | | -eware like below: |
142 | | - |
0 commit comments