feat(agent): Adds label forwarding to log events (#1027)

This PR adds the ability for labels to be forwarded with any log
messages forwarded by the PHP agent.

---------

Co-authored-by: Michal Nowacki <[email protected]>

Author: mfulb

agent/php_newrelic.h

@@ -587,6 +587,12 @@ nrinibool_t
 nriniuint_t
     log_forwarding_log_level; /* newrelic.application_logging.forwarding.log_level
                                */
+nrinibool_t
+    log_forwarding_labels_enabled; /* newrelic.application_logging.forwarding.labels.enabled */
+
+nrinistr_t
+    log_forwarding_labels_exclude; /* newrelic.application_logging.forwarding.labels.exclude */
+
 
 /*
  * Configuration option to toggle code level metrics collection.

agent/php_nrini.c

@@ -3105,6 +3105,22 @@ STD_PHP_INI_ENTRY_EX("newrelic.application_logging.forwarding.context_data.exclu
                      zend_newrelic_globals,
                      newrelic_globals,
                      0)
+STD_PHP_INI_ENTRY_EX("newrelic.application_logging.forwarding.labels.enabled",
+                     "0",
+                     NR_PHP_REQUEST,
+                     nr_boolean_mh,
+                     log_forwarding_labels_enabled,
+                     zend_newrelic_globals,
+                     newrelic_globals,
+                     nr_enabled_disabled_dh)
+STD_PHP_INI_ENTRY_EX("newrelic.application_logging.forwarding.labels.exclude",
+                     "",
+                     NR_PHP_REQUEST,
+                     nr_string_mh,
+                     log_forwarding_labels_exclude,
+                     zend_newrelic_globals,
+                     newrelic_globals,
+                     0)
 
 /*
  * Vulnerability Management

agent/php_txn.c

@@ -536,6 +536,119 @@ static nrobj_t* nr_php_txn_get_labels() {
   return nr_labels_parse(NR_PHP_PROCESS_GLOBALS(env_labels));
 }
 
+static nr_status_t nr_php_txn_collect_label_keys_iter(const char* key,
+                                                      const nrobj_t* value,
+                                                      void* ptr) {
+  nrobj_t* user_data = (nrobj_t*)ptr;
+
+  (void)value;
+
+  if (NULL == key || NULL == user_data) {
+    return NR_FAILURE;
+  }
+
+  nro_set_array_string(user_data, 0, key);
+
+  return NR_SUCCESS;
+}
+
+/*
+ * Purpose : Filter the labels hash to exclude any labels that are in the
+ *           newrelic.application_logging.forwarding.labels.exclude list.
+ *
+ * Params  : 1. The labels hash to filter.
+ *
+ * Returns : A new hash containing the filtered labels.
+ *           If no labels exist or all labels are excluded, then return NULL.
+ *
+ */
+
+nrobj_t* nr_php_txn_get_log_forwarding_labels(nrobj_t* labels) {
+  nrobj_t* label_keys = NULL;
+  nrobj_t* exclude_labels_list = NULL;
+  nrobj_t* exclude_labels_hash = NULL;
+  nrobj_t* log_labels = NULL;
+
+  if (NULL == labels || 0 == nro_getsize(labels)) {
+    nrl_verbosedebug(NRL_TXN, "%s: No labels defined", __FUNCTION__);
+    return NULL;
+  }
+
+  /* if logging labels are disabled then nothing to do */
+  if (0 == NRINI(log_forwarding_labels_enabled)) {
+    nrl_verbosedebug(NRL_TXN, "%s: Log forwarding labels disabled",
+                     __FUNCTION__);
+    return NULL;
+  }
+
+  /* split exclude string on commas - nr_strsplit() will trim leading
+   * and trailing whitespace from each string extracted, as well as
+   * ignoring empty strings after whitespace trimming
+   */
+  exclude_labels_list
+      = nr_strsplit(NRINI(log_forwarding_labels_exclude), ",", 0);
+
+  /* convert to lowercase to support case insensitive search below
+   * will store lowercase version in a hash for more convenient lookup
+   */
+  exclude_labels_hash = nro_new(NR_OBJECT_HASH);
+  for (int i = 0; i < nro_getsize(exclude_labels_list); i++) {
+    char* label = nr_string_to_lowercase(
+        nro_get_array_string(exclude_labels_list, i + 1, NULL));
+
+    if (!nr_strempty(label)) {
+      nro_set_hash_boolean(exclude_labels_hash, label, 1);
+    }
+    nr_free(label);
+  }
+
+  /* original parsed exclude list is no longer needed */
+  nro_delete(exclude_labels_list);
+
+  /* collect label keys from existing labels */
+  label_keys = nro_new(NR_OBJECT_ARRAY);
+  nro_iteratehash(labels, nr_php_txn_collect_label_keys_iter,
+                  (void*)label_keys);
+
+  /* filter by going over the list of label keys, seeing if it exists in the
+   * exclude hash, and if it does skip it otherwise copy key/value for label
+   * to the log labels
+   */
+  log_labels = nro_new(NR_OBJECT_HASH);
+  for (int i = 0; i < nro_getsize(label_keys); i++) {
+    const char* key = NULL;
+    char* lower_key = NULL;
+    int exclude = false;
+
+    key = nro_get_array_string(label_keys, i + 1, NULL);
+    if (NULL == key) {
+      continue;
+    }
+
+    lower_key = nr_string_to_lowercase(key);
+
+    if (1 != nro_get_hash_boolean(exclude_labels_hash, lower_key, NULL)) {
+      nro_set_hash_string(log_labels, key,
+                          nro_get_hash_string(labels, key, NULL));
+    } else {
+      nrl_verbosedebug(NRL_TXN, "%s: Excluding label %s", __FUNCTION__,
+                       NRSAFESTR(key));
+    }
+    nr_free(lower_key);
+  }
+
+  nro_delete(exclude_labels_hash);
+  nro_delete(label_keys);
+
+  /* return NULL if all labels were excluded */
+  if (0 == nro_getsize(log_labels)) {
+    nro_delete(log_labels);
+    log_labels = NULL;
+  }
+
+  return log_labels;
+}
+
 static void nr_php_txn_prepared_statement_destroy(void* sql) {
   nr_free(sql);
 }
@@ -666,6 +779,11 @@ static void nr_php_txn_send_metrics_once(nrtxn_t* txn TSRMLS_DC) {
   nrm_force_add(NRTXN(unscoped_metrics), metname, 0);
   nr_free(metname);
 
+  metname = nr_formatf("Supportability/Logging/Labels/PHP/%s",
+                       FMT_BOOL(nr_txn_log_forwarding_labels_enabled(txn)));
+  nrm_force_add(NRTXN(unscoped_metrics), metname, 0);
+  nr_free(metname);
+
   txn->created_logging_onetime_metrics = true;
 
 #undef FMT_BOOL
@@ -762,6 +880,7 @@ nr_status_t nr_php_txn_begin(const char* appnames,
   nrtxnopt_t opts;
   const char* lic_to_use;
   int pfd;
+  nrobj_t* log_forwarding_labels = NULL;
   nr_attribute_config_t* attribute_config;
   nr_app_info_t info;
   bool is_cli = (0 != NR_PHP_PROCESS_GLOBALS(cli));
@@ -854,6 +973,7 @@ nr_status_t nr_php_txn_begin(const char* appnames,
   opts.log_forwarding_log_level = NRINI(log_forwarding_log_level);
   opts.log_events_max_samples_stored = NRINI(log_events_max_samples_stored);
   opts.log_metrics_enabled = NRINI(log_metrics_enabled);
+  opts.log_forwarding_labels_enabled = NRINI(log_forwarding_labels_enabled);
   opts.message_tracer_segment_parameters_enabled
       = NRINI(message_tracer_segment_parameters_enabled);
 
@@ -917,17 +1037,21 @@ nr_status_t nr_php_txn_begin(const char* appnames,
       &nr_php_app_settings, NR_PHP_PROCESS_GLOBALS(daemon_app_connect_timeout));
   nr_app_info_destroy_fields(&info);
 
-  if (0 == NRPRG(app)) {
+  if (NULL == NRPRG(app)) {
     nrl_debug(NRL_INIT, "unable to begin transaction: app '%.128s' is unknown",
               appnames ? appnames : "");
     return NR_FAILURE;
   }
 
   attribute_config = nr_php_create_attribute_config(TSRMLS_C);
-  NRPRG(txn) = nr_txn_begin(NRPRG(app), &opts, attribute_config);
+  log_forwarding_labels
+      = nr_php_txn_get_log_forwarding_labels(NRPRG(app)->info.labels);
+  NRPRG(txn) = nr_txn_begin(NRPRG(app), &opts, attribute_config,
+                            log_forwarding_labels);
   nrt_mutex_unlock(&(NRPRG(app)->app_lock));
 
   nr_attribute_config_destroy(&attribute_config);
+  nro_delete(log_forwarding_labels);
 
   if (0 == NRPRG(txn)) {
     nrl_debug(NRL_INIT, "no Axiom transaction this time around");

agent/php_txn_private.h

@@ -86,3 +86,16 @@ extern void nr_php_txn_php_package_create_major_metric(void* value,
  * Params  : 1. The current transaction.
  */
 extern void nr_php_txn_create_packages_major_metrics(nrtxn_t* txn);
+
+/*
+ * Purpose : Filter the labels hash to exclude any labels that are in the
+ *           newrelic.application_logging.forwarding.labels.exclude list.
+ *
+ * Params  : 1. The labels hash to filter.
+ *
+ * Returns : A new hash containing the filtered labels.
+ *           If no labels exist or all labels are excluded, then return NULL.
+ *
+ */
+
+extern nrobj_t* nr_php_txn_get_log_forwarding_labels(nrobj_t* labels);

agent/scripts/newrelic.ini.template

@@ -1242,7 +1242,6 @@ newrelic.daemon.logfile = "/var/log/newrelic/newrelic-daemon.log"
 ;          
 ;newrelic.application_logging.forwarding.log_level = "WARNING"
 
-
 ; Setting: newrelic.application_logging.local_decorating.enabled
 ; Type   : boolean
 ; Scope  : per-directory
@@ -1305,6 +1304,34 @@ newrelic.daemon.logfile = "/var/log/newrelic/newrelic-daemon.log"
 ;newrelic.application_logging.forwarding.context_data.include = ""
 ;newrelic.application_logging.forwarding.context_data.exclude = ""
 
+; Setting: newrelic.application_logging.forwarding.labels.enabled
+; Type   : boolean
+; Scope  : per-directory
+; Default: false
+; Info   : Toggles whether the agent adds labels as attributes to log records which
+;          are sent to New Relic.  The labels can be defined by the newrelic.labels
+;          configuration value, and filtered using the
+;          newrelic.application_logging.forwarding.labels.exclude configuration value.
+;
+;newrelic.application_logging.forwarding.labels.enabled = false
+
+; Setting: newrelic.application_logging.forwarding.labels.exclude
+; Type   : string
+; Scope  : per-directory
+; Default: ""
+; Info   : A list of labels to NOT add as attributes to logs which are forwarded
+;          to New Relic.  The values in the list must be separated by commas.
+;
+;          NOTE: The values in this list are compared to label key names in a case
+;                insensitive fashion.  So if an exclude rule for "server" is specified
+;                here then it would exclude keys like "server", "Server", "SERVER", and
+;                any other combination of lower and upper case letters that spell out "server".
+;
+;          Ex:
+;             newrelic.application_logging.forwarding.labels.exclude = "label1, label2"
+;
+;newrelic.application_logging.forwarding.labels.exclude = ""
+
 ; Setting: newrelic.code_level_metrics.enabled
 ; Type   : boolean
 ; Scope  : per-directory

agent/tests/test_txn.c

@@ -288,6 +288,69 @@ static void test_create_agent_php_version_metrics() {
 #undef PHP_VERSION_METRIC_BASE
 #undef AGENT_VERSION_METRIC_BASE
 
+static void test_create_log_forwarding_labels(TSRMLS_D) {
+  nrobj_t* labels = NULL;
+  nrobj_t* log_labels = NULL;
+  char* json = NULL;
+
+  /* Test : Create log forwarding labels with valid key/value pairs */
+  labels = nro_new_hash();
+  nro_set_hash_string(labels, "key1", "value1");
+  nro_set_hash_string(labels, "key2", "value2");
+  nro_set_hash_string(labels, "key3", "value3");
+
+  log_labels = nr_php_txn_get_log_forwarding_labels(labels);
+
+  json = nro_to_json(labels);
+  tlib_pass_if_str_equal(
+      "valid log label creation test",
+      "{\"key1\":\"value1\",\"key2\":\"value2\",\"key3\":\"value3\"}", json);
+
+  nr_free(json);
+  nro_delete(labels);
+  nro_delete(log_labels);
+
+  /* Test : Create log forwarding labels with empty key/value pairs */
+  labels = nro_new_hash();
+  nro_set_hash_string(labels, "", "");
+  nro_set_hash_string(labels, "key", "");
+  nro_set_hash_string(labels, "", "value");
+
+  log_labels = nr_php_txn_get_log_forwarding_labels(labels);
+
+  json = nro_to_json(labels);
+  tlib_pass_if_str_equal("empty string log label creation test",
+                         "{\"key\":\"\"}", json);
+
+  nr_free(json);
+  nro_delete(labels);
+  nro_delete(log_labels);
+
+  /* Test : Create log forwarding labels with NULL key/value pairs */
+  labels = nro_new_hash();
+  nro_set_hash_string(labels, NULL, NULL);
+  nro_set_hash_string(labels, "key", NULL);
+  nro_set_hash_string(labels, NULL, "value");
+
+  log_labels = nr_php_txn_get_log_forwarding_labels(labels);
+
+  json = nro_to_json(labels);
+  tlib_pass_if_str_equal("NULL value log label creation test", "{\"key\":\"\"}",
+                         json);
+
+  nr_free(json);
+  nro_delete(labels);
+  nro_delete(log_labels);
+
+  /* Test : Create log forwarding labels NULL labels object */
+  log_labels = nr_php_txn_get_log_forwarding_labels(NULL);
+  json = nro_to_json(labels);
+  tlib_pass_if_str_equal("NULL object log label creation test", "null", json);
+
+  nr_free(json);
+  nro_delete(log_labels);
+}
+
 tlib_parallel_info_t parallel_info = {.suggested_nthreads = 1, .state_size = 0};
 
 void test_main(void* p NRUNUSED) {
@@ -299,14 +362,16 @@ void test_main(void* p NRUNUSED) {
    * We're setting up our own engine instance because we need to control the
    * attribute configuration.
    */
-  tlib_php_engine_create(
-      "newrelic.transaction_events.attributes.include=request.uri" PTSRMLS_CC);
+  // clang-format off
+  tlib_php_engine_create("newrelic.transaction_events.attributes.include=request.uri" PTSRMLS_CC);
+  // clang-format on
 
   test_handle_fpm_error();
   test_max_segments_config_values();
   test_create_php_version_metric();
   test_create_agent_version_metric();
   test_create_agent_php_version_metrics();
+  test_create_log_forwarding_labels();
 
   tlib_php_engine_destroy();
 }