Developer zone pt.1

docs/admin-gui/deployment-information/index.adoc

@@ -0,0 +1,82 @@
+= Deployment Information
+:page-wiki-name: Deployment Information Type
+:page-upkeep-status: yellow
+
+Intended to store the  information about midPoint deployment: subscription information, deployment name, description, color and so on.
+This data may influence the look and feel of the current midPoint instance.
+
+[%autowidth]
+|===
+| *Attribute name*
+| *Description*
+
+| name
+| Short name of this midPoint deployment.
+The name will be displayed on a prominent place in the user interface, most likely displayed  as a part of the header (on every page).
+The name is usually used to distinguish  between midPoint deployments in the same organization.
+Strings such as "DEVEL", "TEST", "UAT" are often used.
+
+| description
+| Free form description that specifies the details of this deployment.
+It may be significantly long (few paragraps).
+It has no special purpose other then a form of "on-line" documentation for the deployment.
+It will NOT be displayed on every page.
+It will most likely be displayed on a system configuration pages or in configuration summaries.
+
+| headerColor
+| Specification of a color that will be used as a background for a page header.
+The color can be used as a form of easy look and feel customization to match the customer corporate identity.
+But perhaps more often the color will be used to distinguish different midPoint environments in the same organization, e.g. green color for devel environment, blue color for testing, etc.
+
+| skin
+| Specification of the adminLTE skin that will be applied to the base template.
+The base template contains 12 predefined skins including: skin-blue, skin-blue-light skin-yellow, skin-yellow-light, skin-green, skin-green-light, skin-purple, skin-purple-light, skin-red, skin-red-light, skin-black and skin-black-light.
+
+| logo
+| Specification of a logo that will be used in the title bar on every screen.
+This can be used as an easy customization and point to a customer logo.
+Or it may be used as an icon to indicate the environment.
+Can be configured with imageUrl attribute or cssClass attribute.
+Please, be carefull with the width/height of the logo image, the preferable size is: width up to 300px, height up to 60px.You can either use URL or a relative path.
+For custom logos it's best to create a new directory `static-web` under your `midpoint.home` directory and use a relative link.
+
+| customerName
+| Short name of the organization that is end user of the midPoint deployment.
+It is supposed to be a company name, such as "ExAmPLE, Inc." It will be displayed together with subscription information.
+
+| customerUrl
+| URL of the customer web site.
+It will be used as a link target in case that the customer name is displayed as hyperlink.
+
+| partnerName
+| Short name of the organization that deployed this midPoint instance.
+It is usually the name of Evolveum partner.
+It is supposed to be a company name, such as "ExAmPLE, Inc." It will be displayed together with subscription information.
+
+| partnerUrl
+| URL of the partner web site.
+It will be used as a link target in case that the partner name is displayed as hyperlink.
+
+| subscriptionIdentifier
+| Identifier of Evolveum subscription contract that applies to this deployment.
+
+|===
+
+Here is a little example how midPoint look can be configured with deployment information type:
+
+[source,xml]
+----
+<systemConfiguration>
+...
+<deploymentInformation>
+   <headerColor>green</headerColor>
+   <name>TEST</name>
+   <logo>
+      <imageUrl>https://evolveum.com/wp-content/uploads/2015/07/evolveum.png</imageUrl>
+<!--  <imageUrl>static-web/evolveum.png</imageUrl> -->
+   </logo>
+</deploymentInformation>
+</systemConfiguration>
+----
+
+image::image2017-1-30-14-12-38.png[]

docs/diag/logging/log-levels.adoc

@@ -0,0 +1,131 @@
+= Log Levels
+:page-wiki-name: Log Levels
+:page-upkeep-status: orange
+:page-alias: { "parent" : "/midpoint/devel/guides/" }
+
+== Log Levels
+
+[%autowidth,cols="h,1,1,1,1"]
+|===
+| Level | Circumstances | Purpose | Audience | Example
+
+| FATAL
+| Critical errors.
+The system cannot continue operation, will crash or stop working
+| Detect critical system malfunction
+| System administrator, system management (e.g. Network Operation Center)
+| _System out of memory_
+
+
+| ERROR
+| Error that seriously affects the system, but the system as a whole can recover.
+| Detect system misconfiguration of major component failures
+| System administrator, Deployment engineer
+| _Definition of resource c0c010c0-123456-... not found in the repository_
+
+
+| WARNING
+| Suspicious situation.
+System may be able to operate normally, but there may be a hidden or temporary problem or an indication of future error.
+| Pro-active detection of problems
+| System administrator, Deployment engineer
+| _Connection to host foobar timed-out, retrying in 10 seconds_
+
+
+| INFO
+| Important changes in system state, start/stop of important system tasks, etc.
+| Rough system diagnostics (by *non-developer*)
+| Deployment engineer, Advanced system administrator
+| _### MODEL # Enter addObject(ObjectContainer(AccountShadowType(null,Localhost OpenDJ-jack)))_ +
+_Synchronization thread starting_
+
+
+| DEBUG
+| Execution messages, state changes, expression evaluation messages and similar messages for system administrator.
+| Fine-grained system diagnostics (by *non-developer*)
+| Deployment Engineer
+| _Executing outbound expression ... for attribute "cn", resource "ds1", result: cpt. Jack Sparrow_
+
+
+| TRACE
+| Fine-grained messages about execution details.
+| System diagnostics by the developer
+| Developer or advanced engineer
+| _Moooo! Where the hell came the value of "foo" from?_
+
+
+|===
+
+
+== Recommendations For Developers
+
+=== Log Messages
+
+Generaly speaking, avoid messages like:
+
+* `Something bad happened somewhere, HA HA HA`
+
+* `FooTLA threw InvalidContextException while processing line 3324 of STDIN  [ ... 200 lines of stack strace ... ] Caused by NullPointerException at MyThousandLinesLongClass:853.`
+
+
+=== Provide Meaningful Error Message
+
+Provide all the information needed to diagnose the problem.
+Try to include root cause in the message.
+
+.Bad
+[source]
+----
+Error resolving variable "foo"
+----
+
+
+
+.Good
+[source]
+----
+Error resolving variable "foo": Object not found (OID:123456-123456-...)
+----
+
+
+=== Do Not Use Developer's Language
+
+Try to think like a system administrator, not like a developer.
+It will not help administrator that an InvalidArgumentExeption was throws somewhere at the line 42 of `MyDeeplyBurriedUtilClass`. What administrator needs to know is that he has made a typo in the configuration file.
+The only log level that can use any kind of developer's terminology is TRACE.
+Level DEBUG may use some geekish terminology, but should be generally understood by deployment engineers with a very limited knowledge of Java.
+The INFO level and above must not use any of the Java jargon.
+
+.Bad
+[source]
+----
+IDMException was thrown at ProvisioningService:42, root cause: IllegalArgumentException at SchemaParser:32.
+----
+
+
+.Good
+[source]
+----
+Unexpected annotation "<foobar/>" while processing resource schema, attribute "cn", resource "ldap1"
+----
+
+
+=== Provide Context
+
+The messages on WARNING, ERROR and FATAL levels should not depend on the context, they should stand alone and provide all the information needed.
+In other words, the administrator should not need to analyze 100 lines of log file to see where the error happened.
+The reason is that the log level of production systems is usually set to WARNING, therefore the message with lower log levels will not even appear in the log.
+
+.Bad
+[source]
+----
+Error resolving a reference: Object not found
+----
+
+
+.Good
+[source]
+----
+Error resolving variable "foo" in outbound expression processing for variable "cn", resource "ldap42": Object not found (OID:123456-123456-...)
+----
+