diff options
| -rw-r--r-- | docs/APPC API Guide/APPC API Guide.rst | 39 | ||||
| -rw-r--r-- | docs/APPC Client Library Guide/APPC Client Library Guide.rst | 27 | ||||
| -rw-r--r-- | docs/APPC Logging Guide/APPC Logging Guide.rst | 334 | ||||
| -rw-r--r-- | docs/APPC Logging Guide/APPCLoggingArchitecturediagram.png | bin | 0 -> 119759 bytes | |||
| -rw-r--r-- | docs/index.rst | 1 |
5 files changed, 371 insertions, 30 deletions
diff --git a/docs/APPC API Guide/APPC API Guide.rst b/docs/APPC API Guide/APPC API Guide.rst index 9f5effced..7809d37ce 100644 --- a/docs/APPC API Guide/APPC API Guide.rst +++ b/docs/APPC API Guide/APPC API Guide.rst @@ -1,30 +1,27 @@ +.. ============LICENSE_START========================================== +.. =================================================================== +.. Copyright © 2017 AT&T Intellectual Property. All rights reserved. +.. =================================================================== +.. Licensed under the Creative Commons License, Attribution 4.0 Intl. (the "License"); +.. you may not use this documentation except in compliance with the License. +.. You may obtain a copy of the License at +.. +.. https://creativecommons.org/licenses/by/4.0/ +.. +.. Unless required by applicable law or agreed to in writing, software +.. distributed under the License is distributed on an "AS IS" BASIS, +.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +.. See the License for the specific language governing permissions and +.. limitations under the License. +.. ============LICENSE_END============================================ +.. ECOMP is a trademark and service mark of AT&T Intellectual Property. + .. _appc_api_guide: ============================================ ONAP Application Controller (APPC) API Guide ============================================ -Revision History -================ - -+--------------+------------+---------------+--------------------------------------------------------+ -| Date | Revision | Author | Changes | -+--------------+------------+---------------+--------------------------------------------------------+ -| 2017-08-25 | 2.0.0 | Paul Miller | Updates for software contribution in Amsterdam Release | -| | | | | -| | | | **Commands Removed** | -| | | | - LiveUpgrade | -| | | | - ModifyConfig (replaced by ConfigModify) | -| | | | - Rollback | -| | | | - SoftwareUpload | -| | | | - Terminate | -| | | | - Test | -+--------------+------------+---------------+--------------------------------------------------------+ -| 2017-02-06 | 1.0.0 | mjf | copyright updated | -+--------------+------------+---------------+--------------------------------------------------------+ - - - Introduction ============ diff --git a/docs/APPC Client Library Guide/APPC Client Library Guide.rst b/docs/APPC Client Library Guide/APPC Client Library Guide.rst index 8f1fb0a15..26d130537 100644 --- a/docs/APPC Client Library Guide/APPC Client Library Guide.rst +++ b/docs/APPC Client Library Guide/APPC Client Library Guide.rst @@ -1,3 +1,21 @@ +.. ============LICENSE_START========================================== +.. =================================================================== +.. Copyright © 2017 AT&T Intellectual Property. All rights reserved. +.. =================================================================== +.. Licensed under the Creative Commons License, Attribution 4.0 Intl. (the "License"); +.. you may not use this documentation except in compliance with the License. +.. You may obtain a copy of the License at +.. +.. https://creativecommons.org/licenses/by/4.0/ +.. +.. Unless required by applicable law or agreed to in writing, software +.. distributed under the License is distributed on an "AS IS" BASIS, +.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +.. See the License for the specific language governing permissions and +.. limitations under the License. +.. ============LICENSE_END============================================ +.. ECOMP is a trademark and service mark of AT&T Intellectual Property. + .. _appc_client_library: ================================================== @@ -5,15 +23,6 @@ Application Controller (APPC) Client Library Guide ================================================== -Revision History -================ - -+--------------+------------+---------------+--------------------------------------------------+ -| Date | Revision | Author | Changes | -+--------------+------------+---------------+--------------------------------------------------+ -| 2017-08-22 | 1.0.0 | Paul Miller | First draft | -+--------------+------------+---------------+--------------------------------------------------+ - Introduction ============ diff --git a/docs/APPC Logging Guide/APPC Logging Guide.rst b/docs/APPC Logging Guide/APPC Logging Guide.rst new file mode 100644 index 000000000..26aa7f914 --- /dev/null +++ b/docs/APPC Logging Guide/APPC Logging Guide.rst @@ -0,0 +1,334 @@ +.. ============LICENSE_START========================================== +.. =================================================================== +.. Copyright © 2017 AT&T Intellectual Property. All rights reserved. +.. =================================================================== +.. Licensed under the Creative Commons License, Attribution 4.0 Intl. (the "License"); +.. you may not use this documentation except in compliance with the License. +.. You may obtain a copy of the License at +.. +.. https://creativecommons.org/licenses/by/4.0/ +.. +.. Unless required by applicable law or agreed to in writing, software +.. distributed under the License is distributed on an "AS IS" BASIS, +.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +.. See the License for the specific language governing permissions and +.. limitations under the License. +.. ============LICENSE_END============================================ +.. ECOMP is a trademark and service mark of AT&T Intellectual Property. + +APPC Logging +============ + +The APPC modules manage logging functionality according to the logging +configuration file ``org.ops4j.pax.logging.cfg``. APPC configuration defines +the location of the logging configuration file. Each APPC module +configured to generate logs reads the configuration file periodically +and generates logs according to the current logging level. + +Logging Architecture +--------------------- + +The following diagram illustrates the APPC logging architecture. + +|image0| + +Log Types +--------- + +APPC generates several types of logs to capture information needed to +operate, troubleshoot, and report on performance: + +- **Audit Log**: The Audit Log provides a summary view of the + processing of a request – a transaction – within an application. It + captures activity requests received by APPC and includes such + information as the time the activity initiated, when it finishes, and + the API invoked at the component. + +- **Metric Log**: The Metrics Log provides a more detailed view into + the processing of a transaction within APP-C. It captures the + beginning and ending of activities necessary to complete the + transaction within APPC modules, for example, the Dispatcher module, + and other ONAP components such as A&AI. + +- **Error Log**: The Error Log captures INFO, WARN, ERROR, and FATAL + conditions sensed (“exception handled”) by the APPC software + components. + +- • **Debug Log**: The optional Debug Log captures data that may be required to debug and correct abnormal conditions of the application. + + +The APPC modules manage logging functionality according to the logging +configuration file ``org.ops4j.pax.logging.cfg``. APPC configuration defines +the location of the logging configuration file. Each APPC module +configured to generate logs reads the configuration file periodically +and generates logs according to the current logging level. + +Logging Levels +~~~~~~~~~~~~~~ + ++-------------+----------------+---------------+-------------+-------------+------------+ +| **Level** | **Log type** | ++=============+================+===============+=============+=============+============+ +| | | **Errors** | ++-------------+----------------+---------------+-------------+-------------+------------+ +| | **Audit** | **Metrics** | **FATAL** | **ERROR** | **WARN** | ++-------------+----------------+---------------+-------------+-------------+------------+ +| OFF | No | No | No | No | No | ++-------------+----------------+---------------+-------------+-------------+------------+ +| FATAL | Yes | Yes | Yes | No | No | ++-------------+----------------+---------------+-------------+-------------+------------+ +| ERROR | Yes | Yes | Yes | Yes | No | ++-------------+----------------+---------------+-------------+-------------+------------+ +| WARN | Yes | Yes | Yes | Yes | Yes | ++-------------+----------------+---------------+-------------+-------------+------------+ + +Response Codes +~~~~~~~~~~~~~~ + ++----------------------------+--------------------------------+ +| **Response code ranges** | **Error type** | ++============================+================================+ +| 100-199 | Permission errors | ++----------------------------+--------------------------------+ +| 200-299 | Availability errors/Timeouts | ++----------------------------+--------------------------------+ +| 300-399 | Data errors | ++----------------------------+--------------------------------+ +| 400-499 | Schema errors | ++----------------------------+--------------------------------+ +| 500-599 | Business process errors | ++----------------------------+--------------------------------+ +| 900-999 | Unknown errors | ++----------------------------+--------------------------------+ + +Logging Output +--------------- + +APPC generates logging output according to Event and Error Logging Framework(EELF)requirements in the +following format: + +Error Log +~~~~~~~~~~ + ++-------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| **Field** | **Description** | ++=========================+=================================================================================================================================================================================================================================================+ +| Timestamp | Date-time when error occurs in UTC. | ++-------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| RequestID | Universally unique transaction requestID (UUID). | ++-------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| ThreadId | Blank | +| | | +| | This traces processing of a request over a number of threads of a single ONAP component. | ++-------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| ServiceName | Externally advertised API invoked by clients of this component, for example, "Audit", "HealthCheck". | ++-------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| PartnerName | Client or user invoking the API. | ++-------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| TargetEntity | ONAP component/subcomponent or non-ONAP entity invoked for this suboperation’s activities, for example, A&AI, VF, VM, MySql. | ++-------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| TargetServiceName | Known name of External API/operation activities invoked on TargetEntity (ONAP component/subcomponent or non-ONAP entity), for example, VM UUID, VF UUID. | ++-------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| ErrorCategory | WARN or ERROR | ++-------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| ErrorCode | Code representing the error condition according to the error categories. | ++-------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| ErrorDescription | Human readable description of the error - Error name, for example: "CONFIGURATION\_STARTED". | ++-------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| detailMessage | This field may contain any additional information useful in describing the error condition, for example: | +| | | +| | ``Application Controller (APP-C) initialization started at {0}|\`` | +| | ``No resolution is required, this is an informational message|\`` | +| | ``The APP-C component configuration has been started because the component is being initialized or loaded for the first time, or a new instance of the component is being created. This message indicates that the component is starting.`` | ++-------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +Debug Log +~~~~~~~~~ + ++-----------------+------------------------------------------------------------+ +| **Field** | **Description** | ++=================+============================================================+ +| Timestamp | Date-time of the log record. | ++-----------------+------------------------------------------------------------+ +| RequestID | Universally unique transaction requestID (UUID). | ++-----------------+------------------------------------------------------------+ +| DebugInfo | Debug Information | ++-----------------+------------------------------------------------------------+ +| End of Record | Designates the logical end of a multi-line debug record. | ++-----------------+------------------------------------------------------------+ + +Audit Log +~~~~~~~~~ + ++--------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| **Field** | **Description** | ++======================================+===========================================================================================================================================================================================================+ +| BeginTimestamp | Date-time of the start of a request activity. | ++--------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| EndTimestamp | Date-time of the end of a request activity. | ++--------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| RequestID | Universally unique transaction request ID (UUID). | ++--------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| serviceInstanceID | Uniquely identifies a service instance, for example, “service graph”. The primary key, for example, in A&AI, to reference or manage the service instance as a unit. | ++--------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| threadId | Empty | ++--------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| physical/virtual server name | Empty (the value added by the log files collecting agent). | ++--------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| serviceName | Externally advertised API invoked by clients of this component, for example, "Audit", "HealthCheck". | ++--------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| PartnerName | Client or user invoking the API. | ++--------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| StatusCode | High-level success or failure of the request (COMPLETE or ERROR). | ++--------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| ResponseCode | Application specific response code - LCM API error codes categorized according to the logging categories. | ++--------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| ResponseDescription | Human readable description of the application specific response code, for example, "INVALID INPUT PARAMETER - ${detailedErrorMsg}". | ++--------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| instanceUUID | Universally unique identifier to differentiate between multiple instances of the same (named), log writing component - the specific APPC instance UUID. | ++--------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| Category log level | Enum: “INFO” \| “WARN” \|”DEBUG” \| “ERROR” \| “FATAL”. Current log level for the entire APP-C. | ++--------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| Severity | Blank | ++--------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| Server IP address | Blank | ++--------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| ElapsedTime | Elapsed time to complete processing of an API or request at the granularity available to the component system. This value should be the difference between BeginTimestamp and EndTimestamp fields. | ++--------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| Server | VM FQDN if virtualized, otherwise the host name of the logging component. | ++--------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| ClientIPaddress | Requesting remote client application’s IP address if known, otherwise empty. | ++--------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +Metrics Log +~~~~~~~~~~~ + ++-----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| **Field** | **Description** | ++===============================================+==================================================================================================================================================================================================================+ +| BeginTimestamp | Date-time when a suboperation activity is begun in UTC | ++-----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| EndTimestamp | Date-time when a supoperation activity is completed in UTC | ++-----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| RequestID | Universally unique transaction request ID (UUID) | ++-----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| serviceInstanceID | VMUUID, VFUUID | ++-----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| threadId | Optional | ++-----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| physical/virtual server name | Empty if its value can be added by the log files collecting agent. | ++-----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| serviceName | For example: "Audit", "HealthCheck" etc | ++-----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| PartnerName Client or user invoking the API | | ++-----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| TargetEntity | APPC internal subcomponent, for example, MD-SAL, or external component, for example, A&AI, SSH, Netconf, invoked for this suboperation. | ++-----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| TargetServiceName | Operation activities invoked on TargetEntity e.g. A&AI GET generic- vnf | ++-----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| StatusCode | High level success or failure of the suboperation activities (COMPLETE or ERROR) | ++-----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| ResponseCode | Specific response code returned by the suboperation activities. | ++-----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| ResponseDescription | Human readable description of the response code. | ++-----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| instanceUUID | APPC instance ID. | ++-----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| Category log level | Enumerated values: “INFO” \| “WARN” \|”DEBUG” \| “ERROR” \| “FATAL”. | ++-----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| Severity | Empty | ++-----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| Server IP address | The logging component host server’s IP address. | ++-----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| ElapsedTime | Elapsed time to complete processing of the sub operation activities at the granularity available to the component system. This value should be the difference between EndTimestamp and BeginTimestamp fields. | ++-----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| Server | VM FQDN if virtualized, otherwise the host name of the logging component. | ++-----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| ClientIP | Requesting remote client application’s IP address. | ++-----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| class name | Optional. The name of the class that has caused the log record creation. For OO programing languages that support this concept. | ++-----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| Unused | | ++-----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| ProcessKey | Optional | ++-----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| TargetVirtualEntity | Empty | ++-----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| CustomField1 | Empty (specific attributes exposed by developers) | ++-----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| CustomField2 | Empty | ++-----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| CustomField3 | Empty | ++-----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| CustomField4 | Empty | ++-----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| detailMessage | Empty | ++-----------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +Log File Locations +------------------ + +The logging configuration file, ``org.ops4j.pax.logging.cfg`` are located in +appc Git repository: + +``/appc/appc-common/src/main/resources/org/openecomp/appc/org.ops4j.pax.logging.cfg`` + + +The logs are stored at the location defined by the appropriate appender: + +``log4j.appender.error.File=${karaf.data}/log/APPC/appc-error.log`` + +``log4j.appender.debug.file=${karaf.data}/log/APPC/appc-debug.log`` + +``log4j.appender.metric.File=${karaf.data}/log/APPC/appc-metric.log`` + +``log4j.appender.audit.File=${karaf.data}/log/APPC/appc-audit.log`` + + +Enabling APPC Logging +---------------------- + +APPC uses Event and Error Logging Framework (EELF) for application logs. +To enable EELF logging: + +1. Replace the default configuration file located at + ``/opt/opendaylight/current/etc/org.ops4j.pax.logging.cfg`` + + with the configuration file that is checked into git: + + ``/appc/appc-common/src/main/resources/org/openecomp/appc/org.ops4j.pax.logging.cfg`` + +2. Stop and restart ODL controller for the configuration changes to take + effect. + +3. Verify logging changes at the following log paths: + + - ``/opt/opendaylight/current/data/log/eelf/karaf.log`` + This log contains the regular karaf.log output reformatted to use + the EELF MDC properties and the pattern that is configured in the + ``org.ops4j.pax.logging.cfg`` file. + - ``/opt/opendaylight/current/data/log/APPC/<package-name>`` + This directory contains the audit, metric, error, and debug logs that are configured in the ``org.ops4j.pax.logging.cfg`` file. + + +**Note:** + ``/opt/opendaylight/current/data/log/APPC/controller`` contains the logs generated from the package ``org.openecomp.\*`` (all APPC logs) + +- Error.log: alarms –ERROR level logs and above + +- Info.log: INFO level logs only + +- Debug.log: debugging – DEBUG level and above + +- Audit – AUDIT level and above + +Log Rotation +------------ + +Log rotation is performed after every 100 MB size limit is reached. The +log rotation interval is defined as part of the EELF framework. + +.. |image0| image:: APPCLoggingArchitecturediagram.png + :width: 6.49097in + :height: 3.46181in + diff --git a/docs/APPC Logging Guide/APPCLoggingArchitecturediagram.png b/docs/APPC Logging Guide/APPCLoggingArchitecturediagram.png Binary files differnew file mode 100644 index 000000000..4ed155c05 --- /dev/null +++ b/docs/APPC Logging Guide/APPCLoggingArchitecturediagram.png diff --git a/docs/index.rst b/docs/index.rst index f7a2ddd65..33ed50aef 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -7,3 +7,4 @@ APPC Documentation Repository APPC API Guide/APPC API Guide APPC Client Library Guide/APPC Client Library Guide + APPC Logging Guide/APPC Logging Guide |
