ocsf / ocsf-schema

OCSF Schema
Apache License 2.0
635 stars 137 forks source link

Proposal: Expanded Application Lifecycle Schema (Class 6002) #1234

Open pladamgregory opened 4 weeks ago

pladamgregory commented 4 weeks ago

Proposal: Expanded Application Lifecycle Schema (Class 6002)

Description: This proposal introduces additional activities and attributes to the Application Lifecycle (Class 6002) schema. The goal is to enhance this class by covering operational metrics, configuration changes, data access, and user activities.

Application Lifecycle [6002] Class

Category: Application Activity
Application Lifecycle events capture installation, removal, start, stop, and other essential activities related to an application's operation and lifecycle.


Updated Activity IDs

Activity ID

"activity_id": {
  "requirement": "required",
  "enum": {
    "1": {
      "caption": "Install",
      "description": "Install the application."
    },
    "2": {
      "caption": "Remove",
      "description": "Remove the application."
    },
    "3": {
      "caption": "Start",
      "description": "Start the application."
    },
    "4": {
      "caption": "Stop",
      "description": "Stop the application."
    },
    "5": {
      "caption": "Restart",
      "description": "Restart the application."
    },
    "6": {
      "caption": "Enable",
      "description": "Enable the application."
    },
    "7": {
      "caption": "Disable",
      "description": "Disable the application."
    },
    "8": {
      "caption": "Update",
      "description": "Update the application."
    },
    "9": {
      "caption": "Create",
      "description": "Create a configuration or setting within an application."
    },
    "10": {
      "caption": "Delete",
      "description": "Delete a configuration or setting within an application."
    },

New trace_info Object & Profile

Trace Object: Defines key application Trace Information for trace events. (Included Via trace profile)

{
  "caption": "Trace",
  "description": "The attributes associated with an event containing trace data.",
  "extends": "object",
  "name": "trace",
  "attributes": {
    "uid": {
      "description": "The unique identifier used in distributed systems and microservices architecture to track and correlate requests across various components of an application.",
      "requirement": "required"
    },
    "type": {
      "caption": "Trace Type",
      "description": "The trace type, as defined by the trace_type_id.",
      "type": "string_t"
    },
    "type_id": {
      "caption": "Trace Type ID",
      "description": "The normalized identifier of the trace type representing the type of system associated with a particular trace.",
      "type": "integer_t",
      "enum": {
        "0": {
          "caption": "Unknown",
          "description": "The trace_type is unknown."
        },
        "1": {
          "caption": "cloud_providers",
          "description": "Semantic Conventions for cloud providers libraries."
        },
        "2": {
          "caption": "cloud_events",
          "description": "Semantic Conventions for the CloudEvents specification."
        },
        "3": {
          "caption": "database",
          "description": "Semantic Conventions for database operations."
        },
        "4": {
          "caption": "exceptions",
          "description": "Semantic Conventions for exceptions."
        },
        "5": {
          "caption": "faas",
          "description": "Semantic Conventions for Function as a Service (FaaS) operations."
        },
        "6": {
          "caption": "feature_flags",
          "description": "Semantic Conventions for feature flag evaluations."
        },
        "7": {
          "caption": "generative_ai",
          "description": "Semantic Conventions for generative AI (LLM, etc.) operations."
        },
        "8": {
          "caption": "graph_ql",
          "description": "Semantic Conventions for GraphQL implementations."
        },
        "9": {
          "caption": "http",
          "description": "Semantic Conventions for HTTP client and server operations."
        },
        "10": {
          "caption": "messaging",
          "description": "Semantic Conventions for messaging operations and systems."
        },
        "11": {
          "caption": "object_stores",
          "description": "Semantic Conventions for object stores operations."
        },
        "12": {
          "caption": "rpc",
          "description": "Semantic Conventions for RPC client and server operations."
        },
        "13": {
          "caption": "System",
          "description": "System Semantic Conventions."
        },
        "99": {
          "caption": "Other",
          "description": "The event trace_type is not mapped."
        }
      }
    },
    "span": {
      "description": "The attributes associated with an event containing span data.",
      "requirement": "optional"
    },
    "otel_attributes": {
      "requirement": "optional",
      "description": "A dictionary of KV pairs containing the relevant trace attributes present within a trace."
    }
  }
}

New Trace Attributes: Enum of key application Trace Information for trace events.

"trace": {
  "caption": "Trace",
  "description": "The attributes associated with an event containing trace data.",
  "type": "trace"
},
"span": {
  "caption": "Span",
  "description": "The attributes associated with an event containing span data.",
  "type": "span"
},
"otel_attributes": {
  "caption": "OTeL Attributes",
  "description": "A dictionary of KV pairs containing the relevant attributes present within a particular OTeL log within Span for a particular event.",
  "type": "json_t"
},

Updated metric Object & Profile

Metric Object: Defines key application Metric Information for metric events. (Included Via metric profile)

{
  "caption": "Metric",
  "description": "The Metric object defines a simple name/value pair entity for a metric.",
  "extends": "object",
  "name": "metric",
  "attributes": {
    "uid": {
      "description": "The unique identifier of the metric being reported, used to maintain the state of the reporting system for cumulative or delta type metrics.",
      "requirement": "optional"
    },
    "name": {
      "description": "The name of the metric.",
      "requirement": "required"
    },
    "value": {
      "description": "The value of the metric.",
      "requirement": "required"
    },
    "type": {
      "caption": "Metric Type",
      "description": "The metric type, as defined by the metric_type_id.",
      "type": "string_t"
    },
    "type_id": {
      "caption": "Metric Type",
      "description": "The normalized identifier of the metric type.",
      "sibling": "type",
      "type": "integer_t",
      "enum": {
        "0": {
          "caption": "Unknown",
          "description": "The metric type is unknown."
        },
        "1": {
          "caption": "db_client_operation_duration",
          "description": "Duration of database client operations."
        },
        "2": {
          "caption": "db_client_connection_count",
          "description": "Total count of database client connections."
        },
        "3": {
          "caption": "db_client_connection_idle_max",
          "description": "Maximum idle time for database client connections."
        },
        "4": {
          "caption": "db_client_connection_idle_min",
          "description": "Minimum idle time for database client connections."
        },
        "5": {
          "caption": "db_client_connection_max",
          "description": "Maximum allowed database client connections."
        },
        "6": {
          "caption": "db_client_connection_pending_requests",
          "description": "Pending requests waiting for a database connection."
        },

Traces profile

{
  "description": "The attributes that identify trace attributes.",
  "meta": "profile",
  "caption": "Traces",
  "name": "traces",
  "annotations": {
    "group": "primary"
  },
  "attributes": {
    "trace": {
      "requirement": "recommended"
    }
  }
}

Metrics Profile

{
  "description": "The attributes that identify metrics attributes.",
  "meta": "profile",
  "caption": "Metrics",
  "name": "metrics",
  "annotations": {
    "group": "primary"
  },
  "attributes": {
    "metric": {
      "requirement": "recommended"
    }
  }
}
pagbabian-splunk commented 3 weeks ago

Much needed Adam, thanks. I think we should have clear descriptions of what constitutes a component vs a setting in addition to the descriptions and examples.

pladamgregory commented 3 weeks ago

Much needed Adam, thanks. I think we should have clear descriptions of what constitutes a component vs a setting in addition to the descriptions and examples.

I've made some changes to the activities, let me know what you think

jonrau-at-queryai commented 3 weeks ago

This feels like it could be a modification of Application Lifecycle which is a pretty limited Event Class in its own right currently.

pladamgregory commented 3 weeks ago

This feels like it could be a modification of Application Lifecycle which is a pretty limited Event Class in its own right currently.

I've made significant changes here to reflect the collective feedback @pagbabian-splunk @jonrau-at-queryai. Would love a re-review on the new context.

pagbabian-splunk commented 3 weeks ago

I really like the trace and metric profile overlay idea, especially if we can reference and source the attributes back to OTel. We can do that with the new source and references meta data tags. We've been looking for ways to better align with OTel, short of retrofitting the schema to be ECS-based or semantic conventions based, which obviously won't fly at this stage of the game.

rmouritzen-splunk commented 3 weeks ago

The type of otel_attributes can be the more specific object type, which equivalent to a JSON Object.

The JSON (json_t) type is more general and can hold any of the JSON types: array, object, string, boolean, number. For arbitrary key-values, the object type is a closer fit.

pladamgregory commented 3 weeks ago

Updated, thank you for the feedback @rmouritzen-splunk