daifuku

A markdown parser and compiler for log definitions in mobile applications

Usage

Automatic generation of document-based type-safe log implementation code

Step 1

Consider log specifications and write documentation.

• Syntax: docs/syntax.ja.md
• Example: example/LogDefinitions/recipe_search.md

Log definition documents (Markdown)

# recipe_search

An category of events related to recipe search.

## search

An event sent when users perform a recipe search.

- keyword: !string 256
    - Search keyword
- order: SearchOrder
   - latest, popularity

## show_recipe

An event sent when users move from the search results screen to the recipe details screen.

- recipe_id: !integer
    - ID of the selected recipe

Step 2

Run the script.

• Example: example/iOS/generate-log-classes.rb

bundle install
ruby example/iOS/generate-log-classes.rb

After that, the following .swift files will be automatically generated.

ls example/AutoGenerated 
# CommonPayload.swift  LogCategories.swift

Log definition code (Swift)

/// Events on the recipe search screen
public enum RecipeSearch: LogCategory {
    /// An event sent when users perform a recipe search.
    case search(keyword: String, order: SearchOrder)
    ///  An event sent when users move from the search results screen to the recipe details screen.
    case showRecipe(recipeId: Int64)
}

Step 3

Send logs with the enums of the log definition.

Log implementation code (Swift)

// After the search request 
logger.post(
    RecipeSearch.search(
        keyword: keyword, // “egg" 
        order: order // .latest
    )
)

What makes you happy?

Fully documented at all times

Because of the way it works, you cannot implement logging without writing documentation. This means that there will always be documentation.

Happy implementers and happy analysts 😊

Type safety

No unintended values are introduced

Because the possible values, such as character limits, patterns, and numeric ranges, are guaranteed at the type level, it prevents unintended values from entering the log database.

Comfortable to be complemented by IDE

Completion during implementation also improves the development experience and reduces mistakes.

Easy to read for both humans and machines

Markdown is excellent as a format for log definition documents that anyone could easily read and write.

In addition, it was useful to be able to statically analyze both the definition document and the implementation.

For example, mistakes such as "I defined it in the document but forgot to implement it" could be detected automatically.

This mechanism has actually been useful several times in regular CI runs. (It was also useful to be able to notice when a log was accidentally deleted during refactoring, etc.).

Case Study

Git version control in the same repository as the app

In Cookpad (Japan), log definitions and mobile application source code are managed in the same git repository.

Everything in one place (easy to find)

It is all in one place, so there is no need to wander around looking for information in logs.

Background of log definitions can also be checked by following pull requests

It is also possible to run git blame on log markdown definitions and follow pull requests to find out which version of the log was added, who implemented the log, and with what intention.

Articles (Japanese)

• ドキュメントベースの型安全なモバイルアプリ行動ログ基盤の構築 - クックパッド開発者ブログ https://techlife.cookpad.com/entry/2020/11/05/110000
• モバイルアプリの行動ログの「仕込み」を快適にする https://speakerdeck.com/yujif/iosdc-japan-2022-mobile-app-logging

Original Author

@giginet

Contributors

@hiragram @litmon @ksfee684 @aamine @vincentisambart @kalupas226 @yujif

Contributing

This repo is basically read-only. We publish this code for knowledge sharing purposes. Please note that we cannot guarantee continuous maintenance or responses to Issues or Pull Requests.

License

MIT License