A markdown parser and compiler for log definitions in mobile applications

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

Consider log specifications and write documentation.

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

# 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

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

/// 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)
}

Send logs with the enums of the log definition.

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

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 😊

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.

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

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.).

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

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

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.

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

@giginet

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

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.

MIT License