htoooth/Logan

Logan is a lightweight case logging system based on mobile platform.

Logan

Logan is a front-end logging system, which can run in multi environment like Android, iOS, Web etc.

中文说明

Overview

• Android SDK - Android SDK

• iOS SDK - iOS SDK

• Web SDK - Web SDK

• Website - Website

• Server - Server

Getting started

Android SDK

Prerequisites

If you want to build the source, make sure your NDK version is not higher than 16.1.4479499.

Installation

Add the following content in the project build.gradle file:

compile 'com.dianping.android.sdk:logan:1.2.3'

Usage

You must init Logan before you use it. For example:

LoganConfig config = new LoganConfig.Builder()
        .setCachePath(getApplicationContext().getFilesDir().getAbsolutePath())
        .setPath(getApplicationContext().getExternalFilesDir(null).getAbsolutePath()
                + File.separator + "logan_v1")
        .setEncryptKey16("0123456789012345".getBytes())
        .setEncryptIV16("0123456789012345".getBytes())
        .build();
Logan.init(config);

After you init Logan, you can use Logan to write a log. Like this:

Logan.w("test logan", 1);

Logan.w method has two parameters:

• String log: What you want to write;
• int type: Log type. This is very important, best practices below content will show you how to using log type parameter.

If you want to write log to file immediately, you need to call flush function:

Logan.f();

If you want to see all of the log file information, you need to call getAllFilesInfo function:

Map<String, Long> map = Logan.getAllFilesInfo();

• key: Log file date;
• value: Log file size(Bytes).

Upload

this upload method is recommend, you can use this method upload your logs directly into your server. we also provide logan server source code ,you can find it in Logan open souce Repository.

final String url = "https://openlogan.inf.test.sankuai.com/logan/upload.json";
Logan.s(url, loganTodaysDate(), "testAppId", "testUnionid", "testdDviceId", "testBuildVersion", "testAppVersion", new SendLogCallback() {
    @Override
    public void onLogSendCompleted(int statusCode, byte[] data) {
        final String resultData = data != null ? new String(data) : "";
        Log.d(TAG, "upload result, httpCode: " + statusCode + ", details: " + resultData);
    }
});

Logan internal provides logging upload mechanism, in view of the need to upload the log to do the preprocessing. If you want to upload log file, you need to implement a SendLogRunnable:

public class RealSendLogRunnable extends SendLogRunnable {

    @Override
    public void sendLog(File logFile) {
      // logFile: After the pretreatment is going to upload the log file
      // Must Call finish after send log
      finish();
      if (logFile.getName().contains(".copy")) {
				logFile.delete();
			}
    }
}

NOTE: You must call finish method after send log. As written in the code above

Finally you need to call Logan.s method:

Logan.s(date, mSendLogRunnable);

One of the first parameter is date array(yyyy-MM-dd).

Permission

If you upload log file to server, you need INTERNET permission.

If you write log to SD card or read log info from SD card, you need WRITE_EXTERNAL_STORAGE and READ_EXTERNAL_STORAGE permission

iOS & macOS SDK

Installation

Logan supports CocoaPods methods for installing the library in a project.

Podfile

Import Logan in Xcode project, add Logan in podfile.

source 'https://github.com/CocoaPods/Specs.git'
platform :ios, '8.0'

target 'TargetName' do
pod 'Logan', '~> 1.2.5'
end

Then run the following command:

$ pod install

Logan Init

You must init Logan before you use it:

#import "Logan.h"

// important!!! you must replace this key and iv by your own.change key and iv at new version is more secure. we will provide a more secure way to protect your logs in the future.
NSData *keydata = [@"0123456789012345" dataUsingEncoding:NSUTF8StringEncoding]; 
NSData *ivdata = [@"0123456789012345" dataUsingEncoding:NSUTF8StringEncoding];
uint64_t file_max = 10 * 1024 * 1024;
// logan init，incoming 16-bit key，16-bit iv，largest written to the file size(byte)
loganInit(keydata, ivdata, file_max);

#if DEBUG
loganUseASL(YES);
#endif

Usage

Write a log:

logan(1, @"this is a test");

logan method has two parameters:

• String log：What you want to write;
• int type：Log type. This is very important, best practices below content will show you how to using log type parameter.

If you want to write log to file immediately, you need to call flush function:

loganFlush();

If you want to see all of the log file information, you need to call loganAllFilesInfo function:

NSDictionary *map = loganAllFilesInfo();

• key Log file date;
• value: Log file size(Bytes).

Upload

this upload method is recommend, you can use this method upload your logs directly into your server. we also provide logan server source code ,you can find it in Logan open souce Repository.

	loganUpload(@"https://openlogan.inf.test.sankuai.com/logan/upload.json", loganTodaysDate(), @"testAppId", @"testUnionId",@"testDeviceId", ^(NSData * _Nullable data, NSURLResponse * _Nullable response, NSError * _Nullable error) {
		if(error){
			NSLog(@"%@",error);
		}else{
			NSLog(@"upload succeed");
		}
	});

Logan provides a method for obtaining log files and performs preprocessing operations on the logs that need to be uploaded. Log can be uploaded by implementing the network upload function.

    loganUploadFilePath(loganTodaysDate(), ^(NSString *_Nullable filePatch) {
        if (filePatch == nil) {
            return;
        }
        NSString *urlStr = @"http://127.0.0.1:3000/logupload";
        NSURL *url = [NSURL URLWithString:urlStr];
        NSMutableURLRequest *req = [[NSMutableURLRequest alloc] initWithURL:url cachePolicy:NSURLRequestReloadIgnoringCacheData timeoutInterval:60];
        [req setHTTPMethod:@"POST"];
        [req addValue:@"binary/octet-stream" forHTTPHeaderField:@"Content-Type"];
        NSURL *fileUrl = [NSURL fileURLWithPath:filePatch];
        NSURLSessionUploadTask *task = [[NSURLSession sharedSession] uploadTaskWithRequest:req fromFile:fileUrl completionHandler:^(NSData *_Nullable data, NSURLResponse *_Nullable response, NSError *_Nullable error) {
            if (error == nil) {
                NSLog(@"upload success");
            } else {
                NSLog(@"upload failed. error:%@", error);
            }
        }];
        [task resume];
    });

Web SDK

Web SDK ReadMe

Website

Website ReadMe

Server

Server ReadMe

Demo

How to use demo

Log protocol

Best Practices

Before Logan available, log report system is relatively scattered.

To put it simply, the traditional idea is to piece together the problems that appear in the logs of each system, but the new idea is to aggregate and analyze all the logs generated by the user to find the scenes with problems.

The Logan core system consists of four modules:

• Input
• Storage
• BackEnd
• FrontEnd

The new case analysis process is as follows:

Article

A lightweight case logging system based on mobile platform developed by Meituan-Dianping — Logan

Logan: Open Source

Feature

In the future, we will provide a data platform based on Logan big data, including advanced functions such as machine learning, troubleshooting log solution, and big data feature analysis.

Finally, we hope to provide a more complete integrated case analysis ecosystem.

Module	Open Source	Processing	Planning
iOS & macOS	√
Android	√
Web	√
Back End	√
Front End	√
Mini Programs		√

Contributing

For more information about contributing PRs and issues, see our Contribution Guidelines.

Authors

Mobile

• White Bai - baitian0521

• Richard Cao - Richard-Cao

• jiangteng - jiangteng

• yangxiangnan - yangxiangnan

• Mr-xiaojun - Mr-xiaojun

• luoheng - luoheng158

Web

• Sylvia - sylvia1106

• Retrospection - Retrospection

Server

• yuanchao.he - he-yuanchao

• zhilin.luo - zlLuo

See also the list of contributors who participated in this project.

License

Logan is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• mbedtls
• cJSON