[Serve][1/n] Serve logging config API (ray-project#40465)

LoggingConfigSchema will be located in:

- global level: ServeDeploySchema
- application level: ServeApplicationSchema
- deployment level: DeploymentSchema

python/ray/serve/schema.py

@@ -1,6 +1,8 @@
 import json
+import logging
 from collections import Counter
 from dataclasses import dataclass, field
+from enum import Enum
 from typing import Dict, List, Optional, Set, Union
 
 from ray._private.pydantic_compat import (
@@ -63,6 +65,74 @@ def _route_prefix_format(cls, v):
     return v
 
 
+@PublicAPI(stability="alpha")
+class EncodingType(str, Enum):
+    """Encoding type for the serve logs."""
+
+    TEXT = "TEXT"
+    JSON = "JSON"
+
+
+@PublicAPI(stability="alpha")
+class LoggingConfig(BaseModel):
+    """Logging config schema for configuring serve components logs."""
+
+    class Config:
+        extra = Extra.forbid
+
+    encoding: Union[str, EncodingType] = Field(
+        default="TEXT",
+        description=(
+            "Encoding type for the serve logs. Default to 'TEXT'. 'JSON' is also "
+            "supported to format all serve logs into json structure."
+        ),
+    )
+    log_level: Union[int, str] = Field(
+        default=logging.INFO,
+        description=(
+            "Log level for the serve logs. Defaults to INFO. You can set it to "
+            "'DEBUG' to get more detailed debug logs."
+        ),
+    )
+    logs_dir: Union[str, None] = Field(
+        default=None,
+        description=(
+            "Directory to store the logs. Default to None, which means "
+            "logs will be stored in the default directory "
+            "('/tmp/ray/session_latest/logs/serve/...')."
+        ),
+    )
+    enable_access_log: bool = Field(
+        default=True,
+        description=(
+            "Whether to enable access logs for each request. Default to True."
+        ),
+    )
+
+    @validator("encoding")
+    def valid_encoding_format(cls, v):
+
+        if v not in list(EncodingType):
+            raise ValueError(
+                f"Got '{v}' for encoding. Encoding must be one "
+                f"of {set(EncodingType)}."
+            )
+
+        return v
+
+    @validator("log_level")
+    def valid_log_level(cls, v):
+        if isinstance(v, int):
+            return v
+
+        if v not in logging._nameToLevel:
+            raise ValueError(
+                f'Got "{v}" for log_level. log_level must be one of '
+                f"{list(logging._nameToLevel.keys())}."
+            )
+        return logging._nameToLevel[v]
+
+
 @PublicAPI(stability="stable")
 class RayActorOptionsSchema(BaseModel):
     """Options with which to start a replica actor."""
@@ -264,6 +334,10 @@ class DeploymentSchema(BaseModel, allow_population_by_field_name=True):
             "Defaults to no limitation."
         ),
     )
+    logging_config: LoggingConfig = Field(
+        default=DEFAULT.VALUE,
+        description="Logging config for configuring serve deployment logs.",
+    )
 
     @root_validator
     def num_replicas_and_autoscaling_config_mutually_exclusive(cls, values):
@@ -389,6 +463,10 @@ class ServeApplicationSchema(BaseModel):
         default={},
         description="Arguments that will be passed to the application builder.",
     )
+    logging_config: LoggingConfig = Field(
+        default=None,
+        description="Logging config for configuring serve application logs.",
+    )
 
     @property
     def deployment_names(self) -> List[str]:
@@ -604,6 +682,10 @@ class ServeDeploySchema(BaseModel):
     grpc_options: gRPCOptionsSchema = Field(
         default=gRPCOptionsSchema(), description="Options to start the gRPC Proxy with."
     )
+    logging_config: LoggingConfig = Field(
+        default=None,
+        description="Logging config for configuring serve components logs.",
+    )
     applications: List[ServeApplicationSchema] = Field(
         ..., description="The set of applications to run on the Ray cluster."
     )

python/ray/serve/tests/unit/test_schema.py

@@ -1,4 +1,5 @@
 import json
+import logging
 import sys
 import time
 from typing import Dict, List
@@ -16,6 +17,7 @@
 from ray.serve.deployment import deployment_to_schema, schema_to_deployment
 from ray.serve.schema import (
     DeploymentSchema,
+    LoggingConfig,
     RayActorOptionsSchema,
     ServeApplicationSchema,
     ServeDeploySchema,
@@ -722,6 +724,48 @@ def test_extra_fields_invalid_serve_status_schema(self):
             )
 
 
+class TestLoggingConfig:
+    def test_parse_dict(self):
+        schema = LoggingConfig.parse_obj(
+            {
+                "log_level": logging.DEBUG,
+                "encoding": "JSON",
+                "logs_dir": "/my_dir",
+                "enable_access_log": True,
+            }
+        )
+        assert schema.log_level == logging.DEBUG
+        assert schema.encoding == "JSON"
+        assert schema.logs_dir == "/my_dir"
+        assert schema.enable_access_log is True
+
+        # Test string values for log_level.
+        schema = LoggingConfig.parse_obj(
+            {
+                "log_level": "DEBUG",
+            }
+        )
+        assert schema.log_level == logging.DEBUG
+
+    def test_wrong_encoding_type(self):
+        with pytest.raises(ValidationError):
+            LoggingConfig.parse_obj(
+                {
+                    "logging_level": logging.INFO,
+                    "encoding": "NOT_EXIST",
+                    "logs_dir": "/my_dir",
+                    "enable_access_log": True,
+                }
+            )
+
+    def test_default_values(self):
+        schema = LoggingConfig.parse_obj({})
+        assert schema.log_level == logging.INFO
+        assert schema.encoding == "TEXT"
+        assert schema.logs_dir is None
+        assert schema.enable_access_log
+
+
 # This function is defined globally to be accessible via import path
 def global_f():
     return "Hello world!"