From e0a6bcc5e351389e2927533ea8c54be09396f0e4 Mon Sep 17 00:00:00 2001 From: Kai Koenig Date: Tue, 22 Oct 2024 17:36:00 +1300 Subject: [PATCH 1/4] Some documentation improvements around online/offline behaviour. --- README.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 61f34ba..c147b95 100644 --- a/README.md +++ b/README.md @@ -95,7 +95,7 @@ Note that `IncomingMessage` can be `null` if the request was stored because the `IncomingMessage` is the response from the Raygun API - there's nothing in the body, it's just a status code response. If everything went ok, you'll get a 202 response code. Otherwise, we return 401 for incorrect API keys, 403 if you're over your plan limits, or anything in the 500+ range for internal errors. -We use the nodejs http/https library to make the POST to Raygun, you can see more documentation about that callback here: https://nodejs.org/api/http.html#http_http_request_options_callback . +We use the nodejs `http`/`https` library to make the POST to Raygun, you can see more documentation about that callback here: https://nodejs.org/api/http.html#http_http_request_options_callback . You can `await` the call to obtain the result, or use `then/catch`. @@ -444,9 +444,9 @@ const raygunClient = new Raygun.Client().init({ ### Offline caching -Raygun can cache errors thrown by your Node application when it's running in 'offline' mode. By default the offline cache is disabled. Raygun4Node doesn't detect network state change, that is up to the application using the library. +Raygun can cache errors thrown by your Node application when it's running in 'offline' mode. By default the offline cache is disabled. Raygun4Node doesn't detect network state change, that is up to the application using the library to manage online/offline state changes. -Raygun includes an on-disk cache provider out of the box, which required write permissions to the folder you wish to use. You cal also pass in your own cache storage. +Raygun includes an on-disk cache provider out of the box, which requires write permissions to the folder you wish to use. You can also pass in your own cache storage. The default, on-disk cache provider will store crash reports as individual `.json` files in the specified directory. ##### Getting setup with the default offline provide @@ -465,7 +465,7 @@ const raygunClient = new raygun.Client().init({ ##### Changing online/offline state -The Raygun client allows you to set it's online state when your application is running. +The Raygun client allows you to set its online state when your application is running. *To mark as offline* @@ -475,7 +475,9 @@ The Raygun client allows you to set it's online state when your application is r raygunClient.online(); -When marking as online any cached errors will be forwarded to Raygun. +When marking as online any cached errors from the currently configured cache provider will be forwarded to Raygun. This action will respect whatever transport mode (batched or individual HTTP requests) you have currently configured. + +If you change between different cache providers or change the storage directory of the on-disk cache provider, please make sure to trigger processing the offline reports before making such a change. ##### Custom cache provider From 810d8d62ec2e2da695a958f84ebfb20d2e3d221f Mon Sep 17 00:00:00 2001 From: Kai Koenig Date: Wed, 23 Oct 2024 10:58:02 +1300 Subject: [PATCH 2/4] Addressing PR comments --- README.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index c147b95..bb47dec 100644 --- a/README.md +++ b/README.md @@ -444,7 +444,7 @@ const raygunClient = new Raygun.Client().init({ ### Offline caching -Raygun can cache errors thrown by your Node application when it's running in 'offline' mode. By default the offline cache is disabled. Raygun4Node doesn't detect network state change, that is up to the application using the library to manage online/offline state changes. +Raygun can cache errors thrown by your Node application when it's running in 'offline' mode. By default the offline cache is disabled. Raygun4Node does not detect nor manage network state for you. It is up to the application using the library's functionality to manage online/offline state changes. Raygun includes an on-disk cache provider out of the box, which requires write permissions to the folder you wish to use. You can also pass in your own cache storage. The default, on-disk cache provider will store crash reports as individual `.json` files in the specified directory. @@ -455,7 +455,7 @@ When creating your Raygun client you need to pass through a cache path ```javascript const raygunClient = new raygun.Client().init({ apiKey: 'YOUR_API_KEY', - isOffline: false, + isOffline: true, offlineStorageOptions: { cachePath: 'raygunCache/', cacheLimit: 1000 // defaults to 100 errors if you don't set this @@ -463,6 +463,8 @@ const raygunClient = new raygun.Client().init({ }); ``` +Setting `isOffline: true` tells the provider to start in `offline` mode. It will also trigger initialisations of resp. the connection to the cache as specified in `offlineStorageOptions`. + ##### Changing online/offline state The Raygun client allows you to set its online state when your application is running. @@ -507,7 +509,7 @@ const raygunClient = new raygun.Client().init({ See [lib/raygun.offline.ts](lib/raygun.offline.ts) for an example. -We recommend that you limit the number of errors that you are caching so that you don't swamp the clients internet connection sending errors. +We recommend that you limit the number of errors that you are caching so that you don't swamp the client's internet connection sending errors. ### Custom error grouping @@ -623,7 +625,7 @@ View a screencast on creating an app with Node.js and Express.js, then hooking u You can enable logging of debug information from the Raygun client by setting the environment variable `DEBUG=raygun`. The client will then log information about transporting and storing errors, including timing information. ## Contributing -In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using "npm test". +In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using `npm run test`, `npm run eslint`, `npm run tseslint` and `npm run prettier`. ## Release History From f837dcf41b7c0402b37cddcfaac987a4456ab83c Mon Sep 17 00:00:00 2001 From: Kai Koenig Date: Wed, 23 Oct 2024 11:46:33 +1300 Subject: [PATCH 3/4] Update README.md Change suggested by @sumitramanga --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index bb47dec..bb6b838 100644 --- a/README.md +++ b/README.md @@ -463,7 +463,7 @@ const raygunClient = new raygun.Client().init({ }); ``` -Setting `isOffline: true` tells the provider to start in `offline` mode. It will also trigger initialisations of resp. the connection to the cache as specified in `offlineStorageOptions`. +Setting `isOffline: true` tells the provider to start in `offline` mode. It will also trigger initialisations of respectively the connection to the cache as specified in `offlineStorageOptions`. ##### Changing online/offline state From a266e9f244274719f962d88cf8cea62441478d03 Mon Sep 17 00:00:00 2001 From: Kai Koenig Date: Wed, 23 Oct 2024 11:50:26 +1300 Subject: [PATCH 4/4] Update README.md Another tweak. --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index bb6b838..96ec271 100644 --- a/README.md +++ b/README.md @@ -463,7 +463,7 @@ const raygunClient = new raygun.Client().init({ }); ``` -Setting `isOffline: true` tells the provider to start in `offline` mode. It will also trigger initialisations of respectively the connection to the cache as specified in `offlineStorageOptions`. +Setting `isOffline: true` tells the provider to start in `offline` mode. It will also trigger the initialisation of the cache, respectively - if the cache directory already exists - it will connect to the cache as specified in `offlineStorageOptions`. ##### Changing online/offline state