Struct TracebackError

pub struct TracebackError {
    pub message: String,
    pub file: String,
    pub line: u32,
    pub parent: Option<Box<TracebackError>>,
    pub time_created: DateTime<Utc>,
    pub extra_data: Vec<Value>,
    pub project: Option<String>,
    pub computer: Option<String>,
    pub user: Option<String>,
    pub is_parent: bool,
    pub is_handled: bool,
    /* private fields */
}

A custom error struct for handling tracebacks in Rust applications.

This struct is designed to capture error information such as the error message, the file and line where the error occurred, and additional contextual data.

Examples

Creating a new TracebackError with a custom message:

use chrono::{DateTime, Utc};
use serde_json::Value;

let error = traceback_error::traceback!("Custom error message");
println!("{:?}", error);

Fields

• message: A string containing the error message.
• file: A string containing the filename where the error occurred.
• line: An unsigned integer representing the line number where the error occurred.
• parent: An optional boxed TracebackError representing the parent error, if any.
• time_created: A chrono::DateTime<Utc> indicating when the error was created.
• extra_data: A serde_json::Value for storing additional error-related data.
• project: An optional string representing the project name.
• computer: An optional string representing the computer name.
• user: An optional string representing the username.
• is_parent: A boolean indicating if this error is considered a parent error.
• is_handled: A boolean indicating if the error has been handled.
• is_default: A boolean indicating if this error is the default error.

Default Implementation

The Default trait is implemented for TracebackError, creating a default instance with the following values:

• message: “Default message”
• file: The current file’s name (using file!()).
• line: The current line number (using line!()).
• parent: None
• time_created: The Unix epoch time.
• extra_data: Value::Null
• project: None
• computer: None
• user: None
• is_parent: false
• is_handled: false
• is_default: true

Equality Comparison

The PartialEq trait is implemented for TracebackError, allowing you to compare two TracebackError instances for equality based on their message, file, line, and other relevant fields. The is_handled and is_default fields are not considered when comparing for equality.

Dropping Errors

Errors are automatically dropped when they go out of scope, but before they are dropped, they are handled by the TRACEBACK_ERROR_CALLBACK variable. By default, this variable is a function simply set to serialize the error and write it to a JSON file, but the default function can be changed with the set_callback! macro.

Callback Types

The callback function can be either synchronous or asynchronous, depending on the TracebackCallbackType set globally using the TRACEBACK_ERROR_CALLBACK variable. It can be set using the set_callback! macro.

• If TRACEBACK_ERROR_CALLBACK is Some(TracebackCallbackType::Async), an asynchronous callback function is used.
• If TRACEBACK_ERROR_CALLBACK is Some(TracebackCallbackType::Sync), a synchronous callback function is used.
• If TRACEBACK_ERROR_CALLBACK is None, a default callback function is used.

Creating Errors

You can create a new TracebackError instance using the traceback! macro. Additional data can be added using the with_extra_data method, and environment variables are automatically added when the error is being handled. The additional data should be stored in a serde_json::Value struct.

Environment Variables

The with_env_vars method populates the project, computer, and user fields with information obtained from environment variables (CARGO_PKG_NAME, COMPUTERNAME, and USERNAME, respectively) or assigns default values if the environment variables are not present.

Tracing

Tracing can be essential for diagnosing and debugging issues in your applications. When an error occurs, you can create a TracebackError instance to record the error’s details, such as the error message, the location in the code where it occurred, and additional contextual information. Should a function return a TracebackError, it can then be re-captured to trace it even further.

Fields

message: String

file: String

line: u32

parent: Option<Box<TracebackError>>

time_created: DateTime<Utc>

extra_data: Vec<Value>

project: Option<String>

computer: Option<String>

user: Option<String>

is_parent: bool

is_handled: bool

Implementations

impl TracebackError

pub fn new(message: String, file: String, line: u32) -> Self

pub fn with_extra_data(self, extra_data: Value) -> Self

This method allows you to attach additional data to a TracebackError instance. This extra data can be valuable when diagnosing and debugging errors, as it provides context and information related to the error.

Parameters:

• extra_data: A serde_json::Value containing the extra data you want to associate with the error.

Return Value:

• Returns a modified TracebackError instance with the provided extra_data.

Example Usage:

use traceback_error::{traceback, TracebackError, serde_json::json};

fn main() {
    // Create a new TracebackError with extra data
    let error = traceback!().with_extra_data(json!({
        "foo": "bar",
        "a": "b",
        "1": "2"
    }));

    // Now the error instance contains the specified extra data
}

This method is useful when you want to enrich error objects with additional information relevant to the context in which the error occurred. It ensures that relevant data is available for analysis when handling errors in your Rust application.

pub fn with_env_vars(self) -> Self

Adds environment variables to the TracebackError.

This method populates the project, computer, and user fields of the TracebackError based on the values of specific environment variables. If any of these environment variables are not found, default values are used, and the error message reflects that the information is unknown due to the missing environment variables.

Example:

use traceback_error::TracebackError;

// Create a new TracebackError and populate environment variables
let error = TracebackError::new("An error occurred".to_string(), file!().to_string(), line!())
    .with_env_vars();

// The error now contains information about the project, computer, and user from
// environment variables, or default values if the environment variables are missing.

Environment Variables Used:

• CARGO_PKG_NAME: Used to set the project field.
• COMPUTERNAME: Used to set the computer field.
• USERNAME: Used to set the user field.

Returns:

A modified TracebackError with updated project, computer, and user fields.

pub fn with_parent(self, parent: TracebackError) -> Self

The with_parent method allows you to associate a parent error with the current TracebackError instance. This can be useful when you want to create a hierarchical structure of errors, where one error is considered the parent of another.

Parameters:

• parent: A TracebackError instance that you want to set as the parent of the current error.

Return Value:

• Returns a modified TracebackError instance with the specified parent error.

Example:

use traceback_error::TracebackError;

fn main() {
    // Create a new TracebackError
    let parent_error = TracebackError::new("Parent error".to_string(), file!().to_string(), line!());

    // Create a child error with the parent error
    let child_error = TracebackError::new("Child error".to_string(), file!().to_string(), line!())
        .with_parent(parent_error);

    // Now, `child_error` has `parent_error` as its parent
}

The with_parent method is particularly useful when you want to establish relationships between errors, making it easier to understand error hierarchies and diagnose issues.

Trait Implementations

impl Clone for TracebackError

fn clone(&self) -> TracebackError

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for TracebackError

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for TracebackError

fn default() -> Self

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for TracebackError

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Display for TracebackError

This display implementation is recursive, and will print the error and all its parents with a tab in front of each parent.

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Drop for TracebackError

fn drop(&mut self)

Executes the destructor for this type.

impl Error for TracebackError

fn source(&self) -> Option<&(dyn Error + 'static)>

Returns the lower-level source of this error, if any.

fn description(&self) -> &str

👎Deprecated since 1.42.0: use the Display impl or to_string()

fn cause(&self) -> Option<&dyn Error>

👎Deprecated since 1.33.0: replaced by Error::source, which can support downcasting

fn provide<'a>(&'a self, request: &mut Request<'a>)

🔬This is a nightly-only experimental API. (error_generic_member_access)

Provides type-based access to context intended for error reports.

impl Error for TracebackError

fn custom<T: Display>(msg: T) -> Self

Raised when there is general error when deserializing a type.

fn invalid_type(unexp: Unexpected<'_>, exp: &dyn Expected) -> Self

Raised when a Deserialize receives a type different from what it was expecting.

fn invalid_value(unexp: Unexpected<'_>, exp: &dyn Expected) -> Self

Raised when a Deserialize receives a value of the right type but that is wrong for some other reason.

fn invalid_length(len: usize, exp: &dyn Expected) -> Self

Raised when deserializing a sequence or map and the input data contains too many or too few elements.

fn unknown_variant(variant: &str, expected: &'static [&'static str]) -> Self

Raised when a Deserialize enum type received a variant with an unrecognized name.

fn unknown_field(field: &str, expected: &'static [&'static str]) -> Self

Raised when a Deserialize struct type received a field with an unrecognized name.

fn missing_field(field: &'static str) -> Self

Raised when a Deserialize struct type expected to receive a required field with a particular name but that field was not present in the input.

fn duplicate_field(field: &'static str) -> Self

Raised when a Deserialize struct type received more than one of the same field.

impl PartialEq for TracebackError

fn eq(&self, other: &Self) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Serialize for TracebackError

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.