UNPKG

3.83 kBMarkdownView Raw
1# `logs`
2
3Datadog browser logs library.
4
5[Browser support](./BROWSER_SUPPORT.md#logger)
6
7## Setup
8
9### NPM
10
11```
12import { datadogLogs } from '@datadog/browser-logs'
13datadogLogs.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
37What 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
107Types are compatible with TypeScript >= 3.0.
108For earlier version, you can import js sources and use global variable to avoid any compilation issue:
109
110```
111import '@datadog/browser-logs/bundle/datadog-logs';
112
113window.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