Merge pull request #738 from YunoHost/packaging-register-log

[enh] Add doc about log registration feature

packaging_apps.md

@@ -48,6 +48,37 @@ Take a look at the [ownCloud package](https://github.com/Kloadut/owncloud_ynh) f
 ### Helpers
 <a class="btn btn-lg btn-default" href="packaging_apps_helpers_en">Helpers</a>
 
+### Registering a log file
+
+In a lot of case, you might want to register a log file created by your app, to make it available in the webadmin. To register a log, you can create a reference file `/var/log/yunohost/categories/app/APPNAME.yml`.
+
+You can specify a start date by starting the file name with the date formatted as `YYYYMMDD-HHMMSS`.
+
+Example of yml metadata log file:
+```bash
+log_path: /path/to/your/log/file.log
+```
+
+If you want display some context info, you can add:
+```bash
+extra:
+  env:
+    args1: value1
+    args2: value2
+    args3: value3
+```
+
+You can attach the log to an app, domain, service or user like this :
+```bash
+related_to:
+    - ['app', 'APPNAME']
+    - ['service', 'SERVICE1']
+    - ['service', 'SERVICE2']
+    - ['domain', 'DOMAIN.TLD']
+```
+
+This will be used to filter logs and display all log related to an entity like a user, a domain, an app or a service.
+
 ### Test it!
 In order to test your package, you can execute your script standalone as `admin` (do not forget to append required arguments):
 ```bash

packaging_apps_fr.md

@@ -45,6 +45,37 @@ Comme les instances de YunoHost possèdent une architecture unifiée, vous serez
 ### Commandes pratiques
 <a class="btn btn-lg btn-default" href="packaging_apps_helpers_fr">Commandes pratiques</a>
 
+### Référencement des logs
+Dans de nombreuses situations, vous pouvez vouloir indexer un fichier de log pour qu'il soit affiché dans la webadmin. Pour indexer un log, il faut créer un fichier d'indexation dans `/var/log/yunohost/categories/app/APPNAME.yml`.
+
+Il est possible de spécifier la date de début en commençant le nom de fichier par la date `YYYYMMDD-HHMMSS`.
+
+Exemple de fichier de log d'indexation:
+```bash
+log_path: /chemin/vers/le/fichier.log
+```
+
+Il est possible d'afficher des infos complémentaires, la variable env sera affichée dans la partie "Contexte" :
+```bash
+extra:
+  env:
+    args1: value1
+    args2: value2
+    args3: value3
+```
+
+Il est possible de rattacher le log à une application précise et/ou un service, un nom de domaine, une personne :
+```bash
+related_to:
+    - ['app', 'APPNAME']
+    - ['service', 'SERVICE1']
+    - ['service', 'SERVICE2']
+    - ['domain', 'DOMAIN.TLD']
+```
+
+Ces informations seront utilisées pour permettre de filtrer les logs en relation avec une de ces entités application, service, domaine, personne.
+
+
 ### Améliorer la qualité du paquet d’installation
 Vous trouverez ci-dessous une liste des points à vérifier concernant la qualité de vos scripts :
 * Vos scripts utilisent bien `sudo cp -a ../sources/. $final_path` plutôt que `sudo cp -a ../sources/* $final_path` ;