Support log reporting based on PSR-3 (#127)

Author: jmjoy

Cargo.toml

@@ -62,13 +62,13 @@ skywalking = { version = "0.8.0", features = ["management"] }
 skywalking-php-worker = { path = "worker" }
 systemstat = "0.2.3"
 thiserror = "1.0.44"
+time = { version = "0.3", features = ["formatting"] }
 tokio = { version = "1.29.1", features = ["full"] }
 tokio-stream = "0.1.14"
 tonic = { version = "0.8.3", features = ["tls", "tls-roots"] }
 tracing = { version = "0.1.37", features = ["attributes"] }
 tracing-subscriber = { version = "0.3.17", features = ["env-filter", "time", "local-time"] }
 url = "2.4.0"
-time = { version = "0.3", features = ["formatting"] }
 
 [dev-dependencies]
 axum = "0.6.19"

docs/en/configuration/context-injection.md

@@ -1,4 +1,4 @@
-# Context injection
+# Context Injection
 
 If you want to fetch the SkyWalking Context in your PHP code, which is super helpful for debugging and observability,
 You can enable the configuration item `skywalking_agent.inject_context`.

docs/en/configuration/ini-settings.md

@@ -20,9 +20,10 @@ This is the configuration list supported in `php.ini`.
 | skywalking_agent.heartbeat_period                | Agent heartbeat report period. Unit, second.                                                                                                                                                                                                      | 30                        |
 | skywalking_agent.properties_report_period_factor | The agent sends the instance properties to the backend every heartbeat_period * properties_report_period_factor seconds.                                                                                                                          | 10                        |
 | skywalking_agent.enable_zend_observer            | Whether to use `zend observer` instead of `zend_execute_ex` to hook the functions, this feature is only available for PHP8+.                                                                                                                      | Off                       |
-| skywalking_agent.reporter_type                   | Reporter type, optional values are `grpc`, `kafka` and `standalone`.                                                                                                                                                                                            | grpc                      |
+| skywalking_agent.reporter_type                   | Reporter type, optional values are `grpc`, `kafka` and `standalone`.                                                                                                                                                                              | grpc                      |
 | skywalking_agent.kafka_bootstrap_servers         | A list of host/port pairs to use for connect to the Kafka cluster. Only available when `reporter_type` is `kafka`.                                                                                                                                |                           |
 | skywalking_agent.kafka_producer_config           | Configure Kafka Producer configuration in JSON format `{"key": "value}`. Only available when `reporter_type` is `kafka`.                                                                                                                          | {}                        |
 | skywalking_agent.inject_context                  | Whether to enable automatic injection of skywalking context variables (such as `SW_TRACE_ID`). For `php-fpm` mode, it will be injected into the `$_SERVER` variable. For `swoole` mode, it will be injected into the `$request->server` variable. | Off                       |
-| skywalking_agent.instance_name                   | Instance name. You can set `${HOSTNAME}`, refer to [Example #1](https://www.php.net/manual/en/install.fpm.configuration.php)                                                                                                                       |                           |
+| skywalking_agent.instance_name                   | Instance name. You can set `${HOSTNAME}`, refer to [Example #1](https://www.php.net/manual/en/install.fpm.configuration.php)                                                                                                                      |                           |
 | skywalking_agent.standalone_socket_path          | Unix domain socket file path of standalone skywalking php worker. Only available when `reporter_type` is `standalone`.                                                                                                                            |                           |
+| skywalking_agent.psr_logging_level               | The log level reported to SkyWalking, based on PSR-3, one of `Off`, `Debug`, `Info`, Notice`, Warning`, Error`, Critical`, Alert`, Emergency`.                                                                                                    | Off                       |

docs/en/configuration/report-log.md

@@ -0,0 +1,52 @@
+# Report Log
+
+## Overview
+
+In `skywalking-php`, the log level configuration is managed using the `skywalking_agent.psr_logging_level` directive in your `php.ini` file. This configuration defines the minimum log level that will be reported to SkyWalking. The log levels are based on PSR-3 standards and allow you to control the verbosity of the logs sent to SkyWalking.
+
+## Configuration
+
+You can set the `skywalking_agent.psr_logging_level` in your `php.ini` file:
+
+```ini
+skywalking_agent.psr_logging_level = Info
+```
+
+The possible values for this configuration are:
+
+- `Off`: No logs will be reported to SkyWalking.
+- `Debug`: Logs with the level "Debug" or higher will be reported.
+- `Info`: Logs with the level "Info" or higher will be reported.
+- `Notice`: Logs with the level "Notice" or higher will be reported.
+- `Warning`: Logs with the level "Warning" or higher will be reported.
+- `Error`: Logs with the level "Error" or higher will be reported.
+- `Critical`: Logs with the level "Critical" or higher will be reported.
+- `Alert`: Logs with the level "Alert" or higher will be reported.
+- `Emergency`: Logs with the level "Emergency" or higher will be reported.
+
+### Default Value
+
+The default value for `skywalking_agent.psr_logging_level` is set to `Off`, which means no log will be reported to SkyWalking unless specified otherwise.
+
+## How It Works
+
+The `skywalking_agent.psr_logging_level` setting works by hooking into any PHP `LoggerInterface` implementation that follows the PSR-3 standard. The agent listens for log events and compares the log level with the configured value.
+
+- If the log level is **greater than or equal to** the specified `skywalking_agent.psr_logging_level`, the log is reported to SkyWalking.
+- Logs with a level **lower than** the configured value will be ignored and not sent to SkyWalking.
+
+This approach ensures that only relevant logs (those that meet or exceed the configured severity level) are sent to SkyWalking, minimizing noise and focusing on more critical events.
+
+## Example Usage
+
+To report logs of level `Warning` and higher to SkyWalking, you would set the configuration as follows:
+
+```ini
+skywalking_agent.psr_logging_level = Warning
+```
+
+With this setting, logs at the levels `Warning`, `Error`, `Critical`, `Alert`, and `Emergency` will be sent to SkyWalking, while logs at the `Debug`, `Info`, and `Notice` levels will be ignored.
+
+## Conclusion
+
+The `skywalking_agent.psr_logging_level` configuration gives you fine-grained control over the logging behavior of your SkyWalking PHP agent. Adjusting the log level allows you to ensure that only the most important logs are captured, optimizing your monitoring and debugging workflows.

docs/menu.yml

@@ -28,8 +28,10 @@ catalog:
         path: "/en/configuration/ini-settings"
       - name: "Zend Observer"
         path: "/en/configuration/zend-observer"
-      - name: "Context injection"
+      - name: "Context Injection"
         path: "/en/configuration/context-injection"
+      - name: "Report Log"
+        path: "/en/configuration/report-log"
   - name: "Reporter"
     catalog:
       - name: "Kafka Reporter"

src/errors.rs

@@ -44,3 +44,9 @@ impl From<String> for Error {
         Self::Anyhow(anyhow!("{}", e))
     }
 }
+
+impl From<&str> for Error {
+    fn from(e: &str) -> Self {
+        Self::Anyhow(anyhow!("{}", e))
+    }
+}

src/lib.rs

@@ -22,6 +22,7 @@ mod component;
 mod context;
 mod errors;
 mod execute;
+mod log;
 mod module;
 mod plugin;
 mod request;
@@ -113,6 +114,10 @@ const SKYWALKING_AGENT_INJECT_CONTEXT: &str = "skywalking_agent.inject_context";
 /// available when `reporter_type` is `standalone`.
 const SKYWALKING_AGENT_STANDALONE_SOCKET_PATH: &str = "skywalking_agent.standalone_socket_path";
 
+/// The log level reported to SkyWalking, based on PSR-3, one of `Off`, `Debug`,
+/// `Info`, Notice`, Warning`, Error`, Critical`, Alert`, Emergency`.
+const SKYWALKING_AGENT_PSR_LOGGING_LEVEL: &str = "skywalking_agent.psr_logging_level";
+
 #[php_get_module]
 pub fn get_module() -> Module {
     let mut module = Module::new(
@@ -204,6 +209,11 @@ pub fn get_module() -> Module {
         "".to_string(),
         Policy::System,
     );
+    module.add_ini(
+        SKYWALKING_AGENT_PSR_LOGGING_LEVEL,
+        "".to_string(),
+        Policy::System,
+    );
 
     // Hooks.
     module.on_module_init(module::init);

src/log.rs

@@ -0,0 +1,61 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements.  See the NOTICE file distributed with
+// this work for additional information regarding copyright ownership.
+// The ASF licenses this file to You under the Apache License, Version 2.0
+// (the "License"); you may not use this file except in compliance with
+// the License.  You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.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.
+
+use std::fmt::Display;
+
+#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord)]
+pub enum PsrLogLevel {
+    Off,
+    Debug,
+    Info,
+    Notice,
+    Warning,
+    Error,
+    Critical,
+    Alert,
+    Emergency,
+}
+
+impl From<&str> for PsrLogLevel {
+    fn from(s: &str) -> Self {
+        match &*s.to_uppercase() {
+            "DEBUG" => PsrLogLevel::Debug,
+            "INFO" => PsrLogLevel::Info,
+            "NOTICE" => PsrLogLevel::Notice,
+            "WARNING" => PsrLogLevel::Warning,
+            "ERROR" => PsrLogLevel::Error,
+            "CRITICAL" => PsrLogLevel::Critical,
+            "ALERT" => PsrLogLevel::Alert,
+            "EMERGENCY" => PsrLogLevel::Emergency,
+            _ => PsrLogLevel::Off,
+        }
+    }
+}
+
+impl Display for PsrLogLevel {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            PsrLogLevel::Off => "OFF".fmt(f),
+            PsrLogLevel::Debug => "DEBUG".fmt(f),
+            PsrLogLevel::Info => "INFO".fmt(f),
+            PsrLogLevel::Notice => "NOTICE".fmt(f),
+            PsrLogLevel::Warning => "WARNING".fmt(f),
+            PsrLogLevel::Error => "ERROR".fmt(f),
+            PsrLogLevel::Critical => "CRITICAL".fmt(f),
+            PsrLogLevel::Alert => "ALERT".fmt(f),
+            PsrLogLevel::Emergency => "EMERGENCY".fmt(f),
+        }
+    }
+}

src/module.rs

@@ -16,6 +16,7 @@
 use crate::{
     channel::Reporter,
     execute::{register_execute_functions, register_observer_handlers},
+    log::PsrLogLevel,
     util::{get_sapi_module_name, get_str_ini_with_default, IPS},
     worker::init_worker,
     *,
@@ -25,6 +26,7 @@ use once_cell::sync::Lazy;
 use phper::{arrays::ZArr, ini::ini_get, sys};
 use skywalking::{
     common::random_generator::RandomGenerator,
+    logging::logger::{self, Logger},
     trace::tracer::{self, Tracer},
 };
 use std::{
@@ -33,6 +35,7 @@ use std::{
     os::unix::prelude::OsStrExt,
     path::{Path, PathBuf},
     str::FromStr,
+    sync::Arc,
     time::SystemTime,
 };
 use time::format_description::well_known::Rfc3339;
@@ -158,6 +161,12 @@ pub static INJECT_CONTEXT: Lazy<bool> =
 pub const IS_ZEND_OBSERVER_CALLED_FOR_INTERNAL: bool =
     sys::PHP_MAJOR_VERSION > 8 || (sys::PHP_MAJOR_VERSION == 8 && sys::PHP_MINOR_VERSION >= 2);
 
+pub static PSR_LOGGING_LEVEL: Lazy<PsrLogLevel> = Lazy::new(|| {
+    get_str_ini_with_default(SKYWALKING_AGENT_PSR_LOGGING_LEVEL)
+        .as_str()
+        .into()
+});
+
 pub fn init() {
     if !is_enable() {
         return;
@@ -183,6 +192,7 @@ pub fn init() {
     Lazy::force(&KAFKA_BOOTSTRAP_SERVERS);
     Lazy::force(&KAFKA_PRODUCER_CONFIG);
     Lazy::force(&INJECT_CONTEXT);
+    Lazy::force(&PSR_LOGGING_LEVEL);
 
     if let Err(err) = try_init_logger() {
         eprintln!("skywalking_agent: initialize logger failed: {}", err);
@@ -221,12 +231,16 @@ pub fn init() {
     // Initialize Agent worker.
     init_worker();
 
+    let reporter = Arc::new(Reporter::new(&*SOCKET_FILE_PATH));
+
     tracer::set_global_tracer(Tracer::new(
         &*SERVICE_NAME,
         &*SERVICE_INSTANCE,
-        Reporter::new(&*SOCKET_FILE_PATH),
+        reporter.clone(),
     ));
 
+    logger::set_global_logger(Logger::new(&*SERVICE_NAME, &*SERVICE_INSTANCE, reporter));
+
     // Hook functions.
     register_execute_functions();
     register_observer_handlers();

src/plugin/mod.rs

@@ -21,20 +21,25 @@ mod plugin_mongodb;
 mod plugin_mysqli;
 mod plugin_pdo;
 mod plugin_predis;
+mod plugin_psr3;
 mod plugin_redis;
 mod plugin_swoole;
 mod style;
 
-use crate::execute::{AfterExecuteHook, BeforeExecuteHook};
+use crate::{
+    execute::{AfterExecuteHook, BeforeExecuteHook},
+    log::PsrLogLevel,
+    module::PSR_LOGGING_LEVEL,
+};
 use once_cell::sync::Lazy;
-use phper::{eg, objects::ZObj};
+use phper::{classes::ClassEntry, eg, objects::ZObj};
 use skywalking::trace::span::HandleSpanObject;
 use std::{collections::HashMap, ops::Deref, sync::Mutex};
 use tracing::error;
 
 // Register plugins here.
 static PLUGINS: Lazy<Vec<Box<DynPlugin>>> = Lazy::new(|| {
-    vec![
+    let mut plugins: Vec<Box<DynPlugin>> = vec![
         Box::<plugin_curl::CurlPlugin>::default(),
         Box::<plugin_pdo::PdoPlugin>::default(),
         Box::<plugin_mysqli::MySQLImprovedPlugin>::default(),
@@ -46,7 +51,11 @@ static PLUGINS: Lazy<Vec<Box<DynPlugin>>> = Lazy::new(|| {
         Box::<plugin_amqplib::AmqplibPlugin>::default(),
         Box::<plugin_mongodb::MongodbPlugin>::default(),
         Box::<plugin_memcache::MemcachePlugin>::default(),
-    ]
+    ];
+    if *PSR_LOGGING_LEVEL > PsrLogLevel::Off {
+        plugins.push(Box::<plugin_psr3::Psr3Plugin>::default());
+    }
+    plugins
 });
 
 pub type DynPlugin = dyn Plugin + Send + Sync + 'static;
@@ -56,6 +65,10 @@ pub trait Plugin {
 
     fn function_name_prefix(&self) -> Option<&'static str>;
 
+    fn parent_classes(&self) -> Option<Vec<Option<&'static ClassEntry>>> {
+        None
+    }
+
     fn hook(
         &self, class_name: Option<&str>, function_name: &str,
     ) -> Option<(Box<BeforeExecuteHook>, Box<AfterExecuteHook>)>;
@@ -92,19 +105,30 @@ pub fn select_plugin_hook(
 fn select_plugin(class_name: Option<&str>, function_name: &str) -> Option<&'static DynPlugin> {
     let mut selected_plugin = None;
 
-    for plugin in &*PLUGINS {
+    'plugin: for plugin in &*PLUGINS {
         if let Some(class_name) = class_name {
             if let Some(plugin_class_names) = plugin.class_names() {
                 if plugin_class_names.contains(&class_name) {
                     selected_plugin = Some(plugin);
-                    break;
+                    break 'plugin;
+                }
+            }
+            if let Some(parent_classes) = plugin.parent_classes() {
+                if let Ok(class) = ClassEntry::from_globals(class_name) {
+                    // Iterate parent_classes and skip None.
+                    for parent_class in parent_classes.into_iter().flatten() {
+                        if class.is_instance_of(parent_class) {
+                            selected_plugin = Some(plugin);
+                            break 'plugin;
+                        }
+                    }
                 }
             }
         }
         if let Some(function_name_prefix) = plugin.function_name_prefix() {
             if function_name.starts_with(function_name_prefix) {
                 selected_plugin = Some(plugin);
-                break;
+                break 'plugin;
             }
         }
     }