Closes #656 - Use standardized naming schemes in documentation examples

inspectit-ocelot-documentation/docs/configuration/plugin-configuration.md

@@ -16,7 +16,7 @@ In order to enable the plugin system, you need to tell the agent where it should
 ```yaml
 inspectit:
   plugins:
-    path: /path/to/directory
+    path: '/path/to/directory'
 ```
 
 The directory will be scanned on startup of the agent and all found plugins will be loaded.
@@ -30,7 +30,7 @@ The settings for each plugin can be defined under the plugins section based on i
 ```yaml
 inspectit:
   plugins:
-    path: /path/to/directory
+    path: '/path/to/directory'
 
     some-plugin:
       some-config-option: ...

inspectit-ocelot-documentation/docs/instrumentation/instrumentation.md

@@ -12,4 +12,18 @@ Scopes are then used by [rules](instrumentation/rules.md). While scopes define w
 For the definition of rules, [actions](instrumentation/rules.md#actions) are a key concept.
 Long story short: actions allow you to specify _Java snippets in your configuration_ which will be executed to extract any data you want. This can be performance data such as the response time or any kind of business data, e.g. the shopping cart size.
 
-> All instrumentation settings can be changed without restarting the application! They can even be changed while a previous instrumentation is still in progress. In this case the inspectIT Ocelot agent will automatically switch to the new instrumentation as soon as the configuration is loaded.
+> All instrumentation settings can be changed without restarting the application! They can even be changed while a previous instrumentation is still in progress. In this case the inspectIT Ocelot agent will automatically switch to the new instrumentation as soon as the configuration is loaded.
+
+## Naming Convention
+Differentiating between rules, actions and scopes as well as differentiating between keys and values
+in teh configuration can be tricky from time to time.
+Therefore, to increase readability of your configuration files the following naming convention is recommended:
+
+* Scope names always start with "s_", e.g. `s_my_scope`.
+* Action names always start with "a_", e.g. `a_my_action`.
+* Rule names always start with "r_", e.g. `r_my_rule`.
+* Fields which are defined by the user should always be put in single quotations marks, e.g. `input: 'my_input'`. This rule also applies to keys which
+  can be entirely defined by the user, for example when defining the name of a custom action or attribute names.
+
+This naming convention is used both in this documentation and the default configuration provided.
+

inspectit-ocelot-documentation/docs/instrumentation/scopes.md

@@ -13,9 +13,9 @@ Scopes are defined under the configuration key `inspectit.instrumentation.scopes
 inspectit:
   instrumentation:
     scopes:
-      my_scope:
+      's_my_scope':
         # SCOPE_DEFINITION
-      another_scope:
+      's_another_scope':
         # SCOPE_DEFINITION
 ```
 
@@ -76,11 +76,11 @@ A type matcher consists of the following attributes:
 The following example will match against a type which is exactly named `java.util.AbstractList` and is annotated with the annotation `any.Annotation`.
 
 ```yaml
-name: "java.util.AbstractList"
-matcher-mode: "EQUALS_FULLY"
+name: 'java.util.AbstractList'
+matcher-mode: EQUALS_FULLY
 annotations:
-  - name: "any.Annotation"
-    matcher-mode: "EQUALS_FULLY"
+  - name: 'any.Annotation'
+    matcher-mode: EQUALS_FULLY
 ```
 
 ## Method Matcher
@@ -99,14 +99,14 @@ Besides `name`, `matcher-mode` and `annotations`, the method matcher contains th
 The following example will match against all methods which are exactly named `contains`, use the `PUBLIC` visibility modifier, have exactly one argument which is a `java.lang.Object`, are not synchronized and are annotated by the annotation `any.Annotation`.
 
 ```yaml
-name: "contains"
-matcher-mode: "EQUALS_FULLY"
+name: 'contains'
+matcher-mode: EQUALS_FULLY
 visibility: [PUBLIC]
 arguments: ["java.lang.Object"]
 is-synchronized: false
 annotations:
-  - name: "any.Annotation"
-    matcher-mode: "EQUALS_FULLY"
+  - name: 'any.Annotation'
+    matcher-mode: EQUALS_FULLY
 is-constructor: false
 ```
 
@@ -122,51 +122,51 @@ The scope definition's advanced settings contains currently the following two at
 ## Example Scope Definition
 
 The following code-snippet contains an example of a complete scope definitions.
-Note: the following configuration contains all possible attributes even they are not necessary!
+Note: the following configuration contains all possible attributes even though they are not all necessary!
 
 ```yaml
 inspectit:
   instrumentation:
         scopes:
           # the id of the following defined scope element - this example scope targets the ArrayList's contains method
-          example-list-scope:
+          's_example_list_scope':
             # interfaces which have to be implemented
             interfaces:
-              - name: "java.util.List"
-                matcher-mode: "EQUALS_FULLY"
+              - name: 'java.util.List'
+                matcher-mode: EQUALS_FULLY
                 annotations:
-                  - name: "any.Annotation"
-                    matcher-mode: "EQUALS_FULLY"
+                  - name: 'any.Annotation'
+                    matcher-mode: EQUALS_FULLY
             # the superclass which has to be extended
             superclass:
-              name: "java.util.AbstractList"
-              matcher-mode: "EQUALS_FULLY"
+              name: 'java.util.AbstractList'
+              matcher-mode: EQUALS_FULLY
               annotations:
-                - name: "any.Annotation"
-                  matcher-mode: "EQUALS_FULLY"
+                - name: 'any.Annotation'
+                  matcher-mode: EQUALS_FULLY
             # matcher describing the class' name (full qualified)
             type:
-              name: "ArrayList"
-              matcher-mode: "ENDS_WITH"
+              name: 'ArrayList'
+              matcher-mode: ENDS_WITH
               annotations:
-                - name: "any.Annotation"
-                  matcher-mode: "EQUALS_FULLY"
+                - name: 'any.Annotation'
+                  matcher-mode: EQUALS_FULLY
             # the targeted method - each method which matches at least one of the defined matchers will be instrumented
             methods:
-              - name: "contains"
-                matcher-mode: "EQUALS_FULLY"
+              - name: 'contains'
+                matcher-mode: EQUALS_FULLY
                 visibility: [PUBLIC]
                 arguments: ["java.lang.Object"]
                 is-synchronized: false
                 annotations:
-                  - name: "any.Annotation"
-                    matcher-mode: "EQUALS_FULLY"
+                  - name: 'any.Annotation'
+                    matcher-mode: EQUALS_FULLY
               - is-constructor: true
                 visibility: [PUBLIC]
                 arguments: []
                 annotations:
-                  - name: "any.Annotation"
-                    matcher-mode: "EQUALS_FULLY"
+                  - name: 'any.Annotation'
+                    matcher-mode: EQUALS_FULLY
              # advances settings which can be used to specify and narrow the instrumentation
             advanced:
               instrument-only-inherited-methods: false

inspectit-ocelot-documentation/docs/metrics/common-tags.md

@@ -39,8 +39,8 @@ User defined tags can be added to the common tag context by defining the `inspec
    inspectit:
      tags:
        extra:
-         region: us-west-1
-         stage: preprod
+         'region': 'us-west-1'
+         'stage': 'preprod'
    ```
 
 ## Environment Tags

inspectit-ocelot-documentation/docs/metrics/custom-metrics.md

@@ -21,16 +21,16 @@ inspectit:
     definitions:
       '[method/duration]':
         unit: ms
-        description: "the duration from method entry to method exit"
+        description: 'the duration from method entry to method exit'
         views:
           '[method/duration/sum]':
             aggregation: SUM
             tags:
-              method_name : true
+              'method_name' : true
           '[method/duration/count]':
             aggregation: COUNT
             tags:
-              method_name: true
+              'method_name': true
 ```
 
 This snippet defines a metric with the name `method/duration` and the two views `method/duration/sum`

inspectit-ocelot-documentation/docs/tracing/log-correlation.md

@@ -78,8 +78,8 @@ inspectit:
   tracing:
     log-correlation:
       trace-id-auto-injection:
-        prefix: "[TraceID: "
-        suffix: "]"
+        prefix: '[TraceID: '
+        suffix: ']'
 ```
 
 The previous configuration would lead to the following log statement:

inspectit-ocelot-documentation/docs/tracing/privacy.md

@@ -23,8 +23,8 @@ inspectit:
     obfuscation:
       enabled: true
       patterns:
-        - pattern: username
-        - pattern: [a-z]+
+        - pattern: 'username'
+        - pattern: '[a-z]+'
 ```
 
 :::warning Obfuscation Deactivation
@@ -53,7 +53,7 @@ inspectit:
   privacy:
     obfuscation:
       patterns:
-        - pattern: address
+        - pattern: 'address'
 ```
 The following table shows the effect of the previous obfuscation configuration on collected span attributes:
 
@@ -72,7 +72,7 @@ inspectit:
   privacy:
     obfuscation:
       patterns:
-        - pattern: address
+        - pattern: 'address'
           case-insensitive: false   # ignore capitalization
           check-key: true           # this is true by default
           check-data: true          # also check the attributes value