1 | # `logs`
|
2 |
|
3 | Datadog browser logs library.
|
4 |
|
5 | [Browser support](./BROWSER_SUPPORT.md#logger)
|
6 |
|
7 | ## Setup
|
8 |
|
9 | ### NPM
|
10 |
|
11 | ```
|
12 | import { datadogLogs } from '@datadog/browser-logs'
|
13 | datadogLogs.init({
|
14 | clientToken: 'XXX',
|
15 | site: 'datadoghq.com',
|
16 | forwardErrorsToLogs: true,
|
17 | sampleRate: 100
|
18 | })
|
19 | ```
|
20 |
|
21 | ### Bundle
|
22 |
|
23 | ```
|
24 | <script src = 'https://www.datadoghq-browser-agent.com/datadog-logs.js'>
|
25 | <script>
|
26 | window.DD_LOGS.init({
|
27 | clientToken: 'XXX',
|
28 | site: 'datadoghq.com',
|
29 | forwardErrorsToLogs: true,
|
30 | sampleRate: 100
|
31 | });
|
32 | </script>
|
33 | ```
|
34 |
|
35 | ## Public API
|
36 |
|
37 | What we call `Context` is a map `{key: value}` that will be added to the message context.
|
38 |
|
39 | - Init must be called before other methods. Configurable options:
|
40 |
|
41 | - `isCollectingError`: when truthy, we'll automatically forward `console.error` logs, uncaught exceptions and network errors.
|
42 | - `sampleRate`: percentage of sessions to track. Only tracked sessions send logs.
|
43 | - `site`: The site of the Datadog intake to send SDK data to (default: 'datadoghq.com', set to 'datadoghq.eu' to send data to the EU site)
|
44 | - `silentMultipleInit`: prevent logging errors while having multiple Init
|
45 | - `service`: name of the corresponding service
|
46 | - `env`: environment of the service
|
47 | - `version`: version of the service
|
48 |
|
49 | ```
|
50 | init(configuration: {
|
51 | clientToken: string,
|
52 | site?: string,
|
53 | isCollectingError?: boolean,
|
54 | sampleRate?: number,
|
55 | silentMultipleInit?: boolean,
|
56 | service?: string,
|
57 | env?: string,
|
58 | version?: string,
|
59 | })
|
60 | ```
|
61 |
|
62 | - Default logger
|
63 |
|
64 | ```
|
65 | logger.debug | info | warn | error (message: string, messageContext = Context)`
|
66 | logger.log (message: string, messageContext: Context, status? = 'debug' | 'info' | 'warn' | 'error')
|
67 | logger.setLevel (level?: 'debug' | 'info' | 'warn' | 'error')
|
68 | logger.setHandler (handler?: 'http' | 'console' | 'silent')
|
69 | logger.addContext (key: string, value: any) # add one key-value to the logger context
|
70 | logger.removeContext (key: string) # remove one key from the logger context
|
71 | logger.setContext (context: Context) # entirely replace the logger context
|
72 | ```
|
73 |
|
74 | - Custom loggers
|
75 |
|
76 | Custom loggers have the same API than the default logger
|
77 |
|
78 | ```
|
79 | createLogger (name: string, conf?: {
|
80 | level?: 'debug' | 'info' | 'warn' | 'error'
|
81 | handler?: 'http' | 'console' | 'silent'
|
82 | context?: Context
|
83 | }) # create a new logger
|
84 | getLogger (name: string) # retrieve a previously created logger
|
85 | ```
|
86 |
|
87 | - Modify the global context for all loggers
|
88 | ```
|
89 | addLoggerGlobalContext (key: string, value: any) # add one key-value to the default context
|
90 | setLoggerGlobalContext (context: Context) # entirely replace the default context
|
91 | ```
|
92 |
|
93 | ## TypeScript support
|
94 |
|
95 | Types are compatible with TypeScript >= 3.0.
|
96 | For earlier version, you can import js sources and use global variable to avoid any compilation issue:
|
97 |
|
98 | ```
|
99 | import '@datadog/browser-logs/bundle/datadog-logs';
|
100 |
|
101 | window.DD_LOGS.init({
|
102 | clientToken: 'XXX',
|
103 | site: 'datadoghq.com',
|
104 | forwardErrorsToLogs: true,
|
105 | sampleRate: 100
|
106 | });
|
107 | ```
|
108 |
|
\ | No newline at end of file |