Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/truesparrowsystems/applogger
Let's build better mobile apps
https://github.com/truesparrowsystems/applogger
debugging-tool react-native typescript
Last synced: about 1 month ago
JSON representation
Let's build better mobile apps
- Host: GitHub
- URL: https://github.com/truesparrowsystems/applogger
- Owner: TrueSparrowSystems
- License: mit
- Created: 2022-05-16T05:35:12.000Z (over 2 years ago)
- Default Branch: master
- Last Pushed: 2023-08-24T02:12:48.000Z (over 1 year ago)
- Last Synced: 2024-12-18T15:50:32.470Z (about 2 months ago)
- Topics: debugging-tool, react-native, typescript
- Language: TypeScript
- Homepage: https://plgworks.com/applogger
- Size: 4.42 MB
- Stars: 40
- Watchers: 8
- Forks: 0
- Open Issues: 4
-
Metadata Files:
- Readme: README.MD
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# Overview
`AppLogger` is a React Native mobile application framework that helps in minimizing QA issue-reporting time and developer debugging time by providing a web interface for the logs generated and steps taken by the user on a device using the device's IP address. The user can keep track of their sessions and logs, as well as upload, download, and delete them.
## Why AppLogger?
Whenever an issue is reported, developers need issue reproducible steps along with some data to understand, debug and fix it. A lot of time, finding out these reproducible steps becomes a time-consuming effort.
### On the Developer side:
QA data isn't always accurate for replicating the problem, and incomplete data can complicate troubleshooting. As a result, debugging time increases, and the issue may go unresolved since it is not reproducible.
To solve these problems, we need to track the user actions and application state and allow them to be shared easily.
`AppLogger` provides React Native components with customized tracking to minimize the integration effort in any existing or a new application. It also provides a generic wrapper that can be used with any React Native component. A simple `track` function can be used by developers to provide tracking logic to custom methods.
Developers can access the app sessions including the steps and associated logs via the web interface using the device's IP address. The web interface includes a session dashboard with a list of sessions and a session details page that includes device information as well as user action and developer logs.
### On the QA side:
`AppLogger` proves to be a boon by eliminating the need to perform same steps manually for a number of times. Additionally, it simplifies the process to convey the bug's replication steps to developers.
It saves their time by keeping track of the steps in case of Random testing even when the issues are not reproducible.
### Other features of the AppLogger:
- Session management - from the helper menu, the user can stop the current session, start a new one, and can temporarily disable tracking in the current session.
- Download Logs - session logs can be downloaded in HTML or JSON format from the web interface.
- Upload Logs - helper menu allows tracked session logs to be uploaded on any third party services. To use this feature, you must implement the upload function.
- Delete Logs - from the helper menu user can delete session logs.
**Important Note:** The Web Server would work only in a LAN connection i.e. both devices (one on which application is running, other on which web interface is being accessed) should be on the same network. Also, the application must be running in foreground.
## Sample App
We have provided a [sample app](https://github.com/TrueSparrowSystems/applogger/tree/master/example/LogTrackerExample) for implementation reference and a quick sneak-peek.
# Installation
```sh
npm install @truesparrow/applogger --save
```
### Add Dependencies
`AppLogger` has some peer dependencies. It is recommended that you follow the installation instructions of each package to verify that it is properly configured.
- [@react-native-async-storage/async-storage](https://www.npmjs.com/package/@react-native-async-storage/async-storage)
- [react-native-device-info](https://www.npmjs.com/package/react-native-device-info)
- [react-native-fs](https://www.npmjs.com/package/react-native-fs)
- [react-native-get-random-values](https://www.npmjs.com/package/react-native-get-random-values)
- [react-native-http-bridge](https://www.npmjs.com/package/@kingstinct/react-native-http-bridge)
- [react-native-network-info](https://www.npmjs.com/package/react-native-network-info)
- [react-native-shake](https://www.npmjs.com/package/react-native-shake)
- [react-native-exit-app](https://www.npmjs.com/package/react-native-exit-app)
- [react-native-exception-handler](https://www.npmjs.com/package/react-native-exception-handler)
```sh
npm install @react-native-async-storage/async-storage react-native-device-info react-native-fs react-native-get-random-values react-native-http-bridge react-native-network-info react-native-shake react-native-exit-app react-native-exception-handler
```
Navigate to your ios folder and run:
```sh
cd ios
pod install
```
# Usage
To get started, you'll need to call the `useAppLogger` hook in your project's root file. This hook allows you to start and stop the web server, which is necessary for viewing the logs.
`useAppLogger` hook requires a prop of type `AppLoggerParams` as mentioned below.
```typescript
type AppLoggerParams = {
port?: number;
loggerConfig?: LogTrackerConfigInterface;
};
```
`port` is an optional prop on which the server should start, default port is `5561`.
`loggerConfig` is an object of type `LogTrackerConfigInterface`. It's used to configure `AppLogger`. If not provided, it will use default configuration.
```typescript
interface LogTrackerConfigInterface {
writeFrequencyInSeconds: number;
uploadLogs?: (
sessionLogFilePaths: string[],
onUploadComplete: Function,
) => Promise;
clearStorageOnLogUpload: boolean;
isTrackingDisabled?: boolean;
logRotateDurationInHours?: number;
sensitiveDataKeywords?: string[];
}
```
We can configure the following parameters:
- `writeFrequencyInSeconds` - frequency in which logs should be written in storage, default value is `5`.
- `uploadLogs` - Function to upload the logs to any third party storage serivce like s3. Upload will not work unless developer provides a function for it.
- `clearStorageOnLogUpload` - Boolean to clear the storage when logs are uploaded.
- `isTrackingDisabled` - Flag to disable log tracking. Default values - for production env : true, for dev env : false.
- `logRotateDurationInHours` - Flag to clear the logs after certain intervals. If not provided, it will not automatically clear the logs from storage.
- `sensitiveDataKeywords` - Array containing sensitive keys which when encountered in params will be redacted.
Here is a code snippet to configure `AppLogger` on port 8000.
```javascript
import {useAppLogger, HelperMenu} from '@truesparrow/AppLogger';
function App() {
const uploadFile = filePath => {
return new Promise((resolve, reject) => {
s3.upload(filePath)
.then(() => {
resolve(true);
})
.catch(() => {
reject();
});
});
};
const uploaderFunction = (sessionLogFilePaths, onLogUploadComplete) => {
return new Promise(resolve => {
sessionLogFilePaths.forEach((singleSessionLogFilePath, index) => {
uploadFile(singleSessionLogFilePath).then(() => {
if (index == sessionLogFilePaths.length - 1) {
// Call this function to delete log files from local app storage
onLogUploadComplete();
return resolve(true);
}
});
});
});
};
const AppLoggerParams = {
port: 8000,
loggerConfig: {
writeFrequencyInSeconds: 5,
uploadLogs: uploaderFunction,
clearStorageOnLogUpload: false,
isTrackingDisabled: false,
logRotateDurationInHours: 24,
sensitiveDataKeywords: ['password'],
},
};
const {navigationRef, onNavigationStateChange} =
useAppLogger(AppLoggerParams);
return (
);
}
export default App;
```
The helper menu can now be accessed by **shaking your device**.
This will enable you to do the following things:
- Share server URL.
- Upload logs.
- Delete Logs.
- Pause/resume current session.
- Stop current session and start a new session.
You can access your logs using the link below.
```
:/session
```
For example:
```
192.168.0.1:8000/session
```
This link can be shared from the `Share server URL` option in the helper menu.
## Components provided by `AppLogger`
Following are some of the [React Native components](https://reactnative.dev/docs/components-and-apis) that AppLogger provides with tracking.
- Button
- Pressable
- RefreshControl
- Switch
- TextInput
- TouchableHighlight
- TouchableOpacity
- TouchableWithoutFeedback
How to use these components? Just import these components from `@truesparrow/AppLogger` instead of `react-native` and provide a testID.
Eg - To import TouchableWithoutFeedback :
```javascript
import {TouchableWithoutFeedback} from '@truesparrow/AppLogger';
;
```
## How to use Generic component
- The generic component from `AppLogger` can be used to enable tracking for any component other than those listed above.
- The only additional step would be that to wrap the component (or list of components) in a `ComponentWrapper` and provide a `testID` to those components. Apart from that, the wrapped components' logic stays unchanged.
- As it supports all `ViewProps`, the `ComponentWrapper` can be used in place of the `View` Component.
- As of now `ComponentWrapper` works only on a single level, which means it does not track action on children components of wrapped components.
Example snippets:
```javascript
import {ComponentWrapper} from ‘@truesparrow/AppLogger’;
```
```javascript
import {ComponentWrapper} from ‘@truesparrow/AppLogger’;
```
## Supported functions list
Following are the functions that have log tracking enabled in them.
- onChange
- onPress
- onLongPress
- onPressIn
- onPressOut
- onChangeText
- onContentSizeChange
- onEndEditing
- onFocus
- onKeyPress
- onLayout
- onScroll
- onSelectionChange
- onSubmitEditing
- onRefresh
- onValueChange
How to use these functions? No change, you can write it as you would normally do and the `AppLogger` will take care of the rest, provided your component is imported from `@truesparrow/AppLogger` or wrapped inside `ComponentWrapper`.
## Custom Tracking
You can use tracking for any other function that you choose, in addition to the ones listed above. `AppLogger` provides a track interface for custom tracking of activity. Here `type` and `params` are mandatory, while other fields are optional.
```typescript
interface TrackInterface {
id?: string;
description?: string;
type: string;
params: any;
ts?: number;
}
```
Here is an example for custom tracking using `AppLogger`. Consider keeping track of any error that occurs when loading the image. It's implementation could be as follows.
```javascript
import {useCallback} from 'react';
import {Image} from 'react-native';
import {getLogTracker} from '@truesparrow/AppLogger';
function CustomTrackingDemo() {
const imageTestID = 'custom_tracking_demo_image';
const fnOnError = useCallback((error) => {
const logTracker = getLogTracker();
logTracker.track({
description: `Encountered error on image load ${error}`,
type: 'ImageLoadError',
params: {
testId: imageTestID,
},
},
});
}, []);
return
}
```
## Screenshots
### Sample App
### Web Interface
## Contribution
`AppLogger` is an open source project and will always remain free to use. Feel free to report issues, raise PRs for fixes & enhancements. If you think it's cool, please star it 🌟
Made with ❤️ at True Sparrow