regex example (#325)

Author: Mattia Moretti

docs/images/regex1.png

@@ -246,7 +246,72 @@ Examples of custom legend formats that could be defined for metrics associated w
 | oci_objectstorage	| ObjectCount      | {{tier}} ^ {{resourceDisplayName}}              | NORMAL ^ myBucketName             |
 | oci_filestorage   | FileSystemUsage  | resourceId={{resourceId}}                       | resourceId=ocid1.filesystem....   |
 
-Please note that custom labels are supported for OCI resource service metrics only. Custom metrics generated by scripts or by UMA do not support custom labels. 
+Please note that custom labels are supported for OCI resource service metrics only. Custom metrics generated by scripts or by UMA do not support custom labels.
+
+## Label customization using regex Transformation
+In some use case, the Metric Label Customization is not applicable or does not work as expected, due to limitations of dimension key which the plugin is able to capture. The "Rename by Regex" transformation in Grafana allows you to dynamically change the names of fields or series returned by your queries using regular expressions. This is useful for standardizing naming conventions, shortening long names, or extracting parts of a name to reformat it.
+
+**How it Works:**
+
+1.  **Match:** You provide a regular expression (regex) that Grafana attempts to match against existing field or series names.
+2.  **Replace:** You define a replacement pattern. This pattern can include:
+    * Literal text.
+    * Backreferences to "capture groups" from your "Match" regex. Capture groups are parts of your regex enclosed in parentheses `(...)`. You refer to them using `$1` for the first group, `$2` for the second, and so on.
+3.  **Apply to:** You specify whether the renaming logic should apply to "Field name" or "Series name".
+
+**When to Use It (Use Case):**
+
+Use "Rename by Regex" when you need to systematically alter names that follow a pattern, without manually overriding each one.
+
+**Example Use Case: Shortening and Reformatting Server Metric Names**
+
+* **Scenario:** You have metric names like `production_webserver_03_cpu_utilization` or `staging_database_01_memory_usage`. You want to shorten them to `prod_ws_03_cpu` or `stag_db_01_mem` in your panel's legend or table.
+
+* **Configuration:**
+    1.  **Add Transformation:** In your panel editor, go to the "Transform" tab and add the "Rename by regex" transformation.
+    2.  **Match Regex:** `(\w+)_(\w+)server_(\d+)_(\w+)_utilization` (this is just one example, tailor it to your exact naming scheme)
+        * `(\w+)`: Captures the environment (e.g., "production") - becomes `$1`
+        * `(\w+)`: Captures the type (e.g., "web") - becomes `$2`
+        * `(\d+)`: Captures the server number (e.g., "03") - becomes `$3`
+        * `(\w+)`: Captures the metric type (e.g., "cpu") - becomes `$4`
+    3.  **Replace Pattern:** `$1_$2_$3_$4` (This example mainly reorders and removes parts. A more aggressive shortening might be `env:$1_srv:$3_metric:$4`)
+        Or, for the specific shortening example above:
+        * **Match:** `(production|staging)_(\w+)server_(\d+)_(\w+)_(?:utilization|usage)`
+        * **Replace (using conditional logic or simpler patterns if sufficient):**
+            To get `prod_ws_03_cpu`:
+            * Match: `production_webserver_(\d+)_cpu_utilization`
+            * Replace: `prod_ws_$1_cpu`
+            (You might need multiple "Rename by Regex" transformations or a more complex single regex if the patterns vary widely).
+
+            A more general approach for capturing initial letters and numbers:
+            * Match: `(\w{3,4})\w*_(\w{2})\w*_(\d+)_(\w{3})\w*` (This regex is an example and would need careful crafting and testing for your specific names)
+            * Replace: `$1_$2_$3_$4`
+
+    4.  **Apply to:** "Field name" or "Series name" (often "Series name" for legends).
+
+* **Result:** Names like `production_webserver_03_cpu_utilization` would be transformed based on your replace pattern, for instance, to `prod_ws_03_cpu`.
+
+### Regex applied to Metrics Plugin - example
+This is an example dashboard created without using regex, and since it uses custom metrics, the metric label function is not working properly:
+![Metrics dashboard](images/regex1.png)
+
+We can then use this Transformation Rename by Regex:
+
+```
+^.*cluster="([^"]+)".*$
+```
+
+and that will extract the cluster name, as in the following screenshot:
+![Metrics dashboard with regex](images/regex2.png)
+
+
+**Key Things to Remember:**
+
+* **Regex Engine:** Grafana typically uses the RE2 regex engine.
+* **Testing:** Always test your regex patterns. Tools like regex101.com (set to Go/RE2 if possible) are helpful before applying in Grafana. Then verify in the Grafana UI.
+* **Specificity:** Make your "Match" regex as specific as possible to avoid unintended renames.
+* **Order Matters:** If you have multiple transformations, their order of execution can affect the final output.
+
 
 ## Custom Metrics and Namespaces