[kamailio/kamailio] New module/file_out: Module to log custom strings to file (PR #3741)
<!-- Kamailio Pull Request Template -->
<!-- IMPORTANT: - for detailed contributing guidelines, read: https://github.com/kamailio/kamailio/blob/master/.github/CONTRIBUTING.md - pull requests must be done to master branch, unless they are backports of fixes from master branch to a stable branch - backports to stable branches must be done with 'git cherry-pick -x ...' - code is contributed under BSD for core and main components (tm, sl, auth, tls) - code is contributed GPLv2 or a compatible license for the other components - GPL code is contributed with OpenSSL licensing exception -->
#### Pre-Submission Checklist <!-- Go over all points below, and after creating the PR, tick all the checkboxes that apply --> <!-- All points should be verified, otherwise, read the CONTRIBUTING guidelines from above--> <!-- If you're unsure about any of these, don't hesitate to ask on sr-dev mailing list --> - [x] Commit message has the format required by CONTRIBUTING guide - [x] Commits are split per component (core, individual modules, libs, utils, ...) - [x] Each component has a single commit (if not, squash them into one commit) - [x] No commits to README files for modules (changes must be done to docbook files in `doc/` subfolder, the README file is autogenerated)
#### Type Of Change - [ ] Small bug fix (non-breaking change which fixes an issue) - [x] New feature (non-breaking change which adds new functionality) - [ ] Breaking change (fix or feature that would change existing functionality)
#### Checklist: <!-- Go over all points below, and after creating the PR, tick the checkboxes that apply --> - [ ] PR should be backported to stable branches - [x] Tested changes locally - [ ] Related to issue #XXXX (replace XXXX with an open issue number)
#### Description <!-- Describe your changes in detail --> This pull request is intended to introduce a new, straightforward module that can efficiently stream output to files while also handling changes based on a specific interval. The module contains only one function that streams a chunk of text to the current output file handle associated with the given file index.
It's not 100% completed but the basic features are there. Any reviews and of course naming of the module, much appreciated.
---
How the module works:
- Set parameter `base_folder` to define where you want your logs to be saved. - Set `base_filename` (up to 10) to define the names of your files. Each is associated with an index according to the order you defined it. First `base_filename`'s index is 0, second's index is 1 and so on. This is appended with a new timestamp when `interval_seconds` are passed. - Set `interval_seconds` to define how much time before the file is closed and a new one is opened. Right now shared for all files. - Set `extension` to define what should be the extension of files. Right now shared for all files.
Use the provided function `file_out` to write any text (including pvs) to a specific file you want.
--- **Example:**
Define parameters such as: ``` # kamailio.cfg ... loadmodule "file_out.so" modparam("file_out", "base_folder", "/tmp/kamailio/file_out/") modparam("file_out", "base_filename", "accounting") modparam("file_out", "base_filename", "missed_calls") modparam("file_out","interval_seconds", 600) modparam("file_out","extension", ".txt") ...
request_route { ... file_out("0", "Writing to accounting.txt file $rm from $fu (IP:$si:$sp)"); file_out("1", "Writing to missed_calls.txt file $rm from $fu (IP:$si:$sp)"); ... } ```
You can view, comment on, or merge this pull request online at:
https://github.com/kamailio/kamailio/pull/3741
-- Commit Summary --
* file_out: Add new module * file_out: Add docs
-- File Changes --
A src/modules/file_out/Makefile (8) A src/modules/file_out/doc/Makefile (4) A src/modules/file_out/doc/file_out.xml (39) A src/modules/file_out/doc/file_out_admin.xml (191) A src/modules/file_out/file_out.c (380) A src/modules/file_out/types.c (88) A src/modules/file_out/types.h (25)
-- Patch Links --
https://github.com/kamailio/kamailio/pull/3741.patch https://github.com/kamailio/kamailio/pull/3741.diff
@miconda any suggestions regarding the name? Maybe going for the existing "log_" prefix, like log_file, log_file_out or similar?
I have no suggesting about a better name right now, I can think about. Probably `log_` prefix is not suitable, because it does not divert all the log messages like log_custom.
Otherwise upon a quick look, some files are missing the copyright at the top. And I would suggest to add prefix (rename) to the structures used by the module, because Node, Queue ... are too common names.
Thanks for the feedback, the copyright will be added uniformly, and also extend the prefix, sure. Then lets keep the file_out name for now until somebody else has a better idea.
How about `f_log` or `file_log` instead of `file_out`? Also, the first parameter of `file_out` function seems to be an index to the defined filenames. If the order of the `file_out` modparams is changed, then the script has to be updated. It would be more intuitive to use the actual filename instead of the index.
@xkaraman pushed 2 commits.
ae4752366d5a558c54461ca86cdabbd3c3e13f14 file_out: Add copyright 7d08b018e5e54b998366b704c1d82f6c1ce643e4 file_out: Refactor to mach naming conventions
@miconda Thanks for the feedback, fixed.
Thanks for the feedback as well @ovidiusas. The name file_log sounds also good. Regarding the use of an actual file name, its a good idea and can be probably done without performance impact with a fixup function. We will look into that.
I would merge the module manually in some hours (to do the quick rename), and then the further changes can be done directly in the repository.
If performance is crucial, we can keep the index as a first parameter for the `file_out` function and we can change the definition of the `file_out` modparam: ``` modparam("file_out", "base_filename", "0:accounting") modparam("file_out", "base_filename", "1:missed_calls") ``` Populate slot `0` with `accounting` and slot `1` with `missed_calls`. If a slot is re-used, throw an error and exit. If a slot is bigger then `9`, throw an error and exit.
I would not recommend using the word `log` in the name. It has nothing to do wit the internal logging frawork. The module is purely writings text to a file. The core module has basic similar functionality, those functions are not related to logging and this module should also keep away from bringing any confusion with the prefix or suffix. The current name is better for the purpose of the module.
Ok, keep it like this then, no special preference from our side. :-)
How about `f_print` or `file_print`? In the end, it doesn't really matter, but `file_out` doesn't seem to be very intuitive ... or maybe that's just me :) Thanks for contributing this, it is a nice addition!
Merged #3741 into master.
Merged it like this for now as the freeze is coming up * smaller refactorings will be done afterwards (use string in function for names with internal matching, make worker sleep also configurable * a round of tests has been done, but it will be certainly tested more in the next days
Adding a few more details, previous comment was done on mobile, typing there on the web form is not the easiest.
I think that log_file would be a candidate for the name of a module that writes all the logs in a file, similar to log_custom that sends all the log to an udp target. Then having a module named log_file and another one file_log would looks rather confusing.
Renaming can still be done till the branch 5.8 is created, even if it is past the freezing time. First part of testing phase is to tune accordingly the new features to be more suitable for long term maintenance.
Names that came meanwhile in my mind would be: fqwrite (file-queued-write); fqout (fout being rather commonly used to name output file variables, adding q for queuing). This just ideas if renaming is still considered, of course other variant can be used.
-
Daniel-Constantin Mierla -
Henning Westerholt
-
Ovidiu Sas
-
Xenofon Karamanos