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.
|
40 |
|
41 | - Configurable options:
|
42 |
|
43 | - `isCollectingError`: when truthy, we'll automatically forward `console.error` logs, uncaught exceptions and network errors.
|
44 | - `sampleRate`: percentage of sessions to track. Only tracked sessions send logs.
|
45 | - `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)
|
46 | - `silentMultipleInit`: prevent logging errors while having multiple Init
|
47 | - `service`: name of the corresponding service
|
48 | - `env`: environment of the service
|
49 | - `version`: version of the service
|
50 |
|
51 | - Options that must have matching configuration when using `rum` SDK:
|
52 |
|
53 | - `trackSessionAcrossSubdomains`: preserve session across subdomains of the same site (default: `false`)
|
54 | - `useSecureSessionCookie`: use a secure session cookie. This will disable session tracking on insecure (non-HTTPS) connections. (default: `false`)
|
55 | - `useCrossSiteSessionCookie`: use a secure cross-site session cookie. This will allow the Logs SDK to run when the site is loaded from another one (ex: via an iframe). Implies `useSecureSessionCookie`. (default: `false`)
|
56 |
|
57 | ```
|
58 | init(configuration: {
|
59 | clientToken: string,
|
60 | site?: string,
|
61 | isCollectingError?: boolean,
|
62 | sampleRate?: number,
|
63 | silentMultipleInit?: boolean,
|
64 | service?: string,
|
65 | env?: string,
|
66 | version?: string,
|
67 | trackSessionAcrossSubdomains?: boolean,
|
68 | useSecureSessionCookie?: boolean,
|
69 | useCrossSiteSessionCookie?: boolean,
|
70 | })
|
71 | ```
|
72 |
|
73 | - Default logger
|
74 |
|
75 | ```
|
76 | logger.debug | info | warn | error (message: string, messageContext = Context)`
|
77 | logger.log (message: string, messageContext: Context, status? = 'debug' | 'info' | 'warn' | 'error')
|
78 | logger.setLevel (level?: 'debug' | 'info' | 'warn' | 'error')
|
79 | logger.setHandler (handler?: 'http' | 'console' | 'silent')
|
80 | logger.addContext (key: string, value: any) # add one key-value to the logger context
|
81 | logger.removeContext (key: string) # remove one key from the logger context
|
82 | logger.setContext (context: Context) # entirely replace the logger context
|
83 | ```
|
84 |
|
85 | - Custom loggers
|
86 |
|
87 | Custom loggers have the same API than the default logger
|
88 |
|
89 | ```
|
90 | createLogger (name: string, conf?: {
|
91 | level?: 'debug' | 'info' | 'warn' | 'error'
|
92 | handler?: 'http' | 'console' | 'silent'
|
93 | context?: Context
|
94 | }) # create a new logger
|
95 | getLogger (name: string) # retrieve a previously created logger
|
96 | ```
|
97 |
|
98 | - Modify the global context for all loggers
|
99 | ```
|
100 | addLoggerGlobalContext (key: string, value: any) # add one key-value to the default context
|
101 | removeLoggerGlobalContext (key: string) # remove one key of the default context
|
102 | setLoggerGlobalContext (context: Context) # entirely replace the default context
|
103 | ```
|
104 |
|
105 | ## TypeScript support
|
106 |
|
107 | Types are compatible with TypeScript >= 3.0.
|
108 | For earlier version, you can import js sources and use global variable to avoid any compilation issue:
|
109 |
|
110 | ```
|
111 | import '@datadog/browser-logs/bundle/datadog-logs';
|
112 |
|
113 | window.DD_LOGS.init({
|
114 | clientToken: 'XXX',
|
115 | site: 'datadoghq.com',
|
116 | forwardErrorsToLogs: true,
|
117 | sampleRate: 100
|
118 | });
|
119 | ```
|
120 |
|
\ | No newline at end of file |