[VOL-3380] Functional area specific logging - documentation added and existing one modified
Change-Id: I58b3791ae048c284c6ba9d4387cf84be64957534
diff --git a/README.md b/README.md
index 5940819..c08d589 100644
--- a/README.md
+++ b/README.md
@@ -1,31 +1,60 @@
-# How to Build the Golang based OpenONU Adapter
+# OpenONU adapter
-> NOTE that this is a work in progress. A functional version is yet to come.
+The OpenONU adapter provides communication capabilities via OMCI to the ONU devices to be managed by the voltha system.
-## Working with Go Dependencies
-This project uses Go Modules https://github.com/golang/go/wiki/Modules to manage
-dependencies. As a local best pratice this project also vendors the dependencies.
-If you need to update dependencies please follow the Go Modules best practices
-and also perform the following steps before committing a patch:
-```bash
-go mod tidy
-go mod verify
-go mod vendor
+Additional documentation can be found in [docs](./docs)
+
+## Development `make` targets
+
+The `Makefile` contains many commands that are useful in development:
+
+```
+build : Alias for 'docker build'
+clean : Removes any local filesystem artifacts generated by a build
+distclean : Removes any local filesystem artifacts generated by a build or test run
+docker-build : Build openonu adapter docker image (set BUILD_PROFILED=true to also build the profiled image)
+docker-kind-load : Load docker images into a KinD cluster
+docker-push : Push the docker images to an external repository
+help : Print help for each Makefile target
+lint-dockerfile : Perform static analysis on Dockerfile
+lint : Run all lint targets
+lint-mod : Verify the Go dependencies
+lint-sanity : Perform basic code checks on source
+lint-style : Perform lint style checks on source code
+local-lib-go : Copies a local version of the voltha-lib-go dependency into the vendor directory
+local-protos : Copies a local version of the voltha-protos dependency into the vendor directory
+mod-update : Update go mod files
+sca : Runs static code analysis with the golangci-lint tool
+test : Run unit tests
```
-## Building with a Local Copy of `voltha-protos` or `voltha-lib-go`
-If you want to build/test using a local copy or `voltha-protos` or `voltha-lib-go`
-this can be accomplished by using the environment variables `LOCAL_PROTOS` and
-`LOCAL_LIB_GO`. These environment variables should be set to the filesystem
-path where the local source is located, e.g.
+Some highlights:
+
+- It's recommended that you run the `lint`, `sca`, and `test` targets before
+ submitting code changes.
+
+- The `docker-*` targets for building and pushing Docker images depend on the
+ variables `DOCKER_REGISTRY`, `DOCKER_REPOSITORY`, and `DOCKER_TAG` as
+ [described in the CORD documentation](https://guide.opencord.org/developer/test_release_software.html#publish-docker-container-images-to-public-dockerhub-job-docker-publish)
+
+- If you make changes the dependencies in the `go.mod` file, you will need to
+ run `make mod-update` to update the `go.sum` and `vendor` directory.
+
+### Building with a Local Copy of `voltha-protos` or `voltha-lib-go`
+
+If you want to build/test using a local copy of the `voltha-protos` or
+`voltha-lib-go` libraries this can be accomplished by using the environment
+variables `LOCAL_PROTOS` and `LOCAL_LIB_GO`. These environment variables should
+be set to the filesystem path where the local source is located, e.g.:
```bash
-LOCAL\_PROTOS=$HOME/src/voltha-protos
-LOCAL\_LIB\_GO=$HOME/src/voltha-lib-go
+export LOCAL_PROTOS=/path/to/voltha-protos
+export LOCAL_LIB_GO=/path/to/voltha-lib-go
```
-When these environment variables are set the vendored versions of these packages
-will be removed from the `vendor` directory and replaced by coping the files from
-the specified locations to the `vendor` directory. *NOTE:* _this means that
-the files in the `vendor` directory are no longer what is in the `git` repository
-and it will take manual `git` intervention to put the original files back._
+Then run `make local-protos` and/or `make local-lib-go` as is appropriate to
+copy them into the `vendor` directory.
+
+> NOTE: That the files in the `vendor` directory are no longer what is in the
+> most recent commit, and it will take manual `git` intervention to put the
+> original files back.
diff --git a/VERSION b/VERSION
index 2fd65bc..b8c3e62 100755
--- a/VERSION
+++ b/VERSION
@@ -1,2 +1 @@
-2.0.3-dev236
-
+2.0.3-dev237
diff --git a/ONU_Upgrade_Notes.md b/docs/ONU_Upgrade_Notes.md
similarity index 100%
rename from ONU_Upgrade_Notes.md
rename to docs/ONU_Upgrade_Notes.md
diff --git a/PM_Notes.md b/docs/PM_Notes.md
similarity index 100%
rename from PM_Notes.md
rename to docs/PM_Notes.md
diff --git a/docs/Specific_Logging_Notes.md b/docs/Specific_Logging_Notes.md
new file mode 100644
index 0000000..c35a53a
--- /dev/null
+++ b/docs/Specific_Logging_Notes.md
@@ -0,0 +1,95 @@
+# Notes on functional area specific logging of adapter-open-onu
+
+To be able to perform detailed logging even under load conditions,
+the possibility to configure specific log levels for different functional areas was implemented.
+This was done by splitting the code into different packages.
+
+Currently, logging can be configured separately for the following packages:
+
+| package | functional content |
+| :------: | :----------------------- |
+| almgr | utilities to manage alarm notifications |
+| avcfg | anig and vlan configuration functionality |
+| common | global utility functions and OMCI request handling |
+| core | RPC interfaces towards the core and device handler functionality |
+| devdb | utilities for internal device ME DB |
+| mib | MIB upload/download and ONU device handling |
+| omcitst | OMCI test request handling |
+| pmmgr | utilities to manage onu metrics |
+| swupg | onu sw upgrade functionality |
+| uniprt | utilities for UNI port configuration |
+
+
+## Configuration example
+
+The following sections provide some examples on how to use the API to set logs.
+
+### _Set adapter-open-onu default log level to “WARN”:_
+```
+$ voltctl log level list
+COMPONENTNAME PACKAGENAME LEVEL
+read-write-core default DEBUG
+adapter-open-onu default DEBUG
+adapter-open-olt default DEBUG
+global default WARN
+
+$ voltctl log level set WARN adapter-open-onu
+COMPONENTNAME PACKAGENAME STATUS ERROR
+adapter-open-onu default Success
+
+$ voltctl log level list
+COMPONENTNAME PACKAGENAME LEVEL
+adapter-open-olt default DEBUG
+global default WARN
+adapter-open-onu default WARN
+read-write-core default DEBUG
+```
+
+### _Display existing log packages of adapter-open-onu:_
+
+```
+$ voltctl log package list adapter-open-onu
+COMPONENTNAME PACKAGENAME
+adapter-open-onu default
+adapter-open-onu github.com/opencord/voltha-lib-go/v5/pkg/adapters/common
+adapter-open-onu github.com/opencord/voltha-lib-go/v5/pkg/config
+adapter-open-onu github.com/opencord/voltha-lib-go/v5/pkg/db
+adapter-open-onu github.com/opencord/voltha-lib-go/v5/pkg/db/kvstore
+adapter-open-onu github.com/opencord/voltha-lib-go/v5/pkg/events
+adapter-open-onu github.com/opencord/voltha-lib-go/v5/pkg/flows
+adapter-open-onu github.com/opencord/voltha-lib-go/v5/pkg/kafka
+adapter-open-onu github.com/opencord/voltha-lib-go/v5/pkg/log
+adapter-open-onu github.com/opencord/voltha-lib-go/v5/pkg/meters
+adapter-open-onu github.com/opencord/voltha-lib-go/v5/pkg/probe
+adapter-open-onu github.com/opencord/voltha-openonu-adapter-go/internal/pkg/almgr
+adapter-open-onu github.com/opencord/voltha-openonu-adapter-go/internal/pkg/avcfg
+adapter-open-onu github.com/opencord/voltha-openonu-adapter-go/internal/pkg/common
+adapter-open-onu github.com/opencord/voltha-openonu-adapter-go/internal/pkg/core
+adapter-open-onu github.com/opencord/voltha-openonu-adapter-go/internal/pkg/devdb
+adapter-open-onu github.com/opencord/voltha-openonu-adapter-go/internal/pkg/mib
+adapter-open-onu github.com/opencord/voltha-openonu-adapter-go/internal/pkg/omcitst
+adapter-open-onu github.com/opencord/voltha-openonu-adapter-go/internal/pkg/pmmgr
+adapter-open-onu github.com/opencord/voltha-openonu-adapter-go/internal/pkg/swupg
+adapter-open-onu github.com/opencord/voltha-openonu-adapter-go/internal/pkg/uniprt
+adapter-open-onu main
+```
+
+### _Set log level of packages “almgr” and “avcfg” to “DEBUG”:_
+
+```
+$ voltctl log level set DEBUG adapter-open-onu#github.com/opencord/voltha-openonu-adapter-go/internal/pkg/almgr
+COMPONENTNAME PACKAGENAME STATUS ERROR
+adapter-open-onu github.com/opencord/voltha-openonu-adapter-go/internal/pkg/almgr Success
+
+$ voltctl log level set DEBUG adapter-open-onu#github.com/opencord/voltha-openonu-adapter-go/internal/pkg/avcfg
+COMPONENTNAME PACKAGENAME STATUS ERROR
+adapter-open-onu github.com/opencord/voltha-openonu-adapter-go/internal/pkg/avcfg Success
+
+$ voltctl log level list adapter-open-onu
+COMPONENTNAME PACKAGENAME LEVEL
+adapter-open-onu github.com/opencord/voltha-openonu-adapter-go/internal/pkg/almgr DEBUG
+adapter-open-onu github.com/opencord/voltha-openonu-adapter-go/internal/pkg/avcfg DEBUG
+adapter-open-onu default WARN
+```
+
+> Note: In order to cancel the specific log level for individual packets, they have to be configured again with the globally set log level.
\ No newline at end of file