From 534e5b0eb51f32aedd8f97a4ff0bc3ee992c90d8 Mon Sep 17 00:00:00 2001 From: Roger Johansson Date: Tue, 21 Nov 2023 18:06:10 +0100 Subject: [PATCH 1/3] add example readmes --- _examples/actor-autorespond/readme.md | 32 +++++++++++++++++++++++++ _examples/actor-deadletter/readme.md | 34 +++++++++++++++++++++++++++ 2 files changed, 66 insertions(+) create mode 100644 _examples/actor-autorespond/readme.md create mode 100644 _examples/actor-deadletter/readme.md diff --git a/_examples/actor-autorespond/readme.md b/_examples/actor-autorespond/readme.md new file mode 100644 index 00000000..0d685d6e --- /dev/null +++ b/_examples/actor-autorespond/readme.md @@ -0,0 +1,32 @@ +## AI Generated Content. Please report issues + +# Go Example with Proto.Actor Auto Response + +## Introduction +This Go example demonstrates the use of the Auto Response feature in the Proto.Actor framework. It illustrates how an actor can automatically generate a response to a message. + +## Description +In this example, we define `myAutoResponder` and `myAutoResponse` types to use the Auto Response feature of Proto.Actor. This feature allows an actor to automatically create a response message upon receiving a specific type of message. This is particularly useful for acknowledging message receipt in systems like the ClusterPubSub feature. + +## Setup +To run this example, ensure you have the following prerequisites: +- Go programming environment +- Proto.Actor for Go installed in your environment + +You can install Proto.Actor using the following command: +```bash +go get -u github.com/asynkron/protoactor-go +``` + +## Running the Example +1. Copy the code into a file, for example, `main.go`. +2. Run the program using: +```bash +go run main.go +``` + +## Additional Notes +- The `myAutoResponder` struct implements the `GetAutoResponse` method which is essential for the Auto Response mechanism. +- The `main` function initializes an actor system, creates an actor, and sends a message to it. The response is then printed to the console. + +This example provides a basic understanding of how to implement and use the Auto Response feature in the Proto.Actor framework in Go. diff --git a/_examples/actor-deadletter/readme.md b/_examples/actor-deadletter/readme.md new file mode 100644 index 00000000..0ab1b67a --- /dev/null +++ b/_examples/actor-deadletter/readme.md @@ -0,0 +1,34 @@ +## AI Generated Content. Please report issues + +# Go Example: Handling Invalid PIDs with Deadletter in Proto.Actor + +## Introduction +This Go example demonstrates handling invalid PIDs (Process Identifiers) using the deadletter mechanism in the Proto.Actor framework. It showcases how messages sent to invalid PIDs are managed by the deadletter handler. + +## Description +The example sets up a scenario where messages are sent to an invalid PID. This triggers the deadletter mechanism, which is a way to handle messages that cannot be delivered to their intended recipients. The program includes options to adjust the rate of message sending, the throttle of deadletter logs, and the duration of the message-sending loop. + +## Setup +To run this example, ensure the following are installed: +- Go programming environment +- Proto.Actor for Go + +Install Proto.Actor with the following command: +```bash +go get -u github.com/asynkron/protoactor-go +``` + +## Running the Example +1. Save the code in a file, for example, `main.go`. +2. Run the program using: +```bash +go run main.go +``` +You can also pass optional flags like `--rate`, `--throttle`, and `--duration` to adjust the behavior of the example. + +## Additional Notes +- The `main` function initializes an actor system with a custom configuration for deadletter handling. +- The program sends messages to a deliberately invalid PID to demonstrate how the deadletter mechanism works in Proto.Actor. +- The example is useful for understanding the deadletter process in actor-based systems, especially for error handling and debugging. + +This example provides insight into managing undeliverable messages in the Proto.Actor framework using Go. From f920af406b3eddc92f00ef276a6053359cf675fd Mon Sep 17 00:00:00 2001 From: Roger Johansson Date: Tue, 21 Nov 2023 18:12:49 +0100 Subject: [PATCH 2/3] add example readmes --- _examples/actor-helloworld/readme.md | 33 +++++++++++++++++++ _examples/actor-jaegertracing/README.md | 40 +++++++++++++++++++---- _examples/actor-lifecycleevents/readme.md | 33 +++++++++++++++++++ 3 files changed, 99 insertions(+), 7 deletions(-) create mode 100644 _examples/actor-helloworld/readme.md create mode 100644 _examples/actor-lifecycleevents/readme.md diff --git a/_examples/actor-helloworld/readme.md b/_examples/actor-helloworld/readme.md new file mode 100644 index 00000000..e639a364 --- /dev/null +++ b/_examples/actor-helloworld/readme.md @@ -0,0 +1,33 @@ +## AI Generated Content. Please report issues + +# Go Example: Hello World with Proto.Actor + +## Introduction +This simple Go example demonstrates a basic "Hello World" scenario using the Proto.Actor framework. It's a straightforward introduction to actor-based programming in Go. + +## Description +The program defines a `hello` message struct and a `helloActor` actor type. The actor receives a `hello` message and logs a greeting to the console. This example is designed to be an entry point for understanding how actors receive and process messages in Proto.Actor. + +## Setup +Ensure the following are installed to run this example: +- Go programming environment +- Proto.Actor for Go + +To install Proto.Actor, use the command: +```bash +go get -u github.com/asynkron/protoactor-go +``` + +## Running the Example +1. Save the code in a file, named `main.go`, for example. +2. Execute the program with: +```bash +go run main.go +``` + +## Additional Notes +- The `helloActor` struct implements the `Receive` method, which is triggered upon message arrival. +- The `main` function creates an actor system, spawns a `helloActor`, and sends it a `hello` message. +- This example is a great starting point for those new to the Proto.Actor framework and actor-based systems in Go. + +This example provides a basic yet illustrative demonstration of using actors in Go with the Proto.Actor framework. diff --git a/_examples/actor-jaegertracing/README.md b/_examples/actor-jaegertracing/README.md index 3cc514a2..d90db4a3 100644 --- a/_examples/actor-jaegertracing/README.md +++ b/_examples/actor-jaegertracing/README.md @@ -1,4 +1,31 @@ -# Jeager Tracing / OpenTracing example +## AI Generated Content. Please report issues + +# Go Example: Jaeger Tracing with Proto.Actor + +## Introduction +This Go example demonstrates how to integrate Jaeger tracing with the Proto.Actor framework. It provides a practical demonstration of implementing distributed tracing in a microservices architecture using Jaeger. + +## Description +The program initializes a Jaeger tracer and sets up a simple actor system with Proto.Actor. It sends messages between actors and traces these interactions using Jaeger. This example is particularly useful for understanding how distributed tracing works in complex systems where understanding the flow of requests and responses is crucial. + +## Setup +Ensure you have the following to run this example: +- Go programming environment +- Proto.Actor for Go +- Jaeger Tracing libraries + +Install the necessary libraries using: +```bash +go get -u github.com/asynkron/protoactor-go +go get -u github.com/uber/jaeger-client-go +``` + +## Running the Example +1. Save the code in a file, for example, `main.go`. +2. Execute the program: +```bash +go run main.go +``` To run the example an instance of Jaeger server is required running locally. The easiest way to run a jaeger server instance is starting it using the included docker-compose file like this @@ -7,11 +34,10 @@ instance is starting it using the included docker-compose file like this docker-compose -f ./examples/jaegertracing/docker-compose.yaml up -d ``` -And the just run the example: -```bash -go run ./examples/jaegertracing/main.go -``` +## Additional Notes +- The `initJaeger` function sets up Jaeger tracing with basic configuration. +- The program creates an actor system and uses Jaeger to trace the message flow between actors. +- This example is ideal for those looking to implement distributed tracing in their Go applications using Jaeger and Proto.Actor. -After the test has run (and also during), traces can found using the Jaeger UI started at http://localhost:16686. - +This example is an insightful demonstration of using Jaeger for distributed tracing in a Go application with the Proto.Actor framework. diff --git a/_examples/actor-lifecycleevents/readme.md b/_examples/actor-lifecycleevents/readme.md new file mode 100644 index 00000000..624c81a8 --- /dev/null +++ b/_examples/actor-lifecycleevents/readme.md @@ -0,0 +1,33 @@ +## AI Generated Content. Please report issues + +# Go Example: Actor Lifecycle Events with Proto.Actor + +## Introduction +This Go example demonstrates handling actor lifecycle events in the Proto.Actor framework. It showcases the various stages in an actor's life, from initialization to shutdown. + +## Description +The program creates an actor system and demonstrates the lifecycle events of an actor, including `Started`, `Stopping`, `Stopped`, and `Restarting`. It also sends a `hello` message to the actor to illustrate interaction during its active state. This example is valuable for understanding the lifecycle management of actors in actor-based systems. + +## Setup +To run this example, ensure you have: +- Go programming environment +- Proto.Actor for Go + +Install Proto.Actor with: +```bash +go get -u github.com/asynkron/protoactor-go +``` + +## Running the Example +1. Copy the code into a file, named `main.go`, for instance. +2. Run the program: +```bash +go run main.go +``` + +## Additional Notes +- The `helloActor` struct handles different lifecycle events and logs corresponding messages. +- The `main` function initializes an actor system, spawns a `helloActor`, sends it a message, and then stops it to demonstrate the lifecycle events. +- This example is a practical demonstration for those interested in the lifecycle management of actors in the Proto.Actor framework. + +The example provides a clear view of the lifecycle events of an actor in a Go application using the Proto.Actor framework. From 711c740ecf9c7535af569e4ce507d26661e78737 Mon Sep 17 00:00:00 2001 From: Roger Johansson Date: Tue, 21 Nov 2023 18:20:43 +0100 Subject: [PATCH 3/3] add example readmes --- _examples/actor-autorespond/readme.md | 3 +- _examples/actor-deadletter/readme.md | 3 +- _examples/actor-helloworld/readme.md | 3 +- _examples/actor-jaegertracing/README.md | 3 +- _examples/actor-lifecycleevents/readme.md | 3 +- _examples/actor-logging/main.go | 4 +++ _examples/actor-logging/readme.md | 35 +++++++++++++++++++++++ _examples/actor-supervision/readme.md | 33 +++++++++++++++++++++ 8 files changed, 77 insertions(+), 10 deletions(-) create mode 100644 _examples/actor-logging/readme.md create mode 100644 _examples/actor-supervision/readme.md diff --git a/_examples/actor-autorespond/readme.md b/_examples/actor-autorespond/readme.md index 0d685d6e..520dcf93 100644 --- a/_examples/actor-autorespond/readme.md +++ b/_examples/actor-autorespond/readme.md @@ -19,8 +19,7 @@ go get -u github.com/asynkron/protoactor-go ``` ## Running the Example -1. Copy the code into a file, for example, `main.go`. -2. Run the program using: + ```bash go run main.go ``` diff --git a/_examples/actor-deadletter/readme.md b/_examples/actor-deadletter/readme.md index 0ab1b67a..b6531a28 100644 --- a/_examples/actor-deadletter/readme.md +++ b/_examples/actor-deadletter/readme.md @@ -19,8 +19,7 @@ go get -u github.com/asynkron/protoactor-go ``` ## Running the Example -1. Save the code in a file, for example, `main.go`. -2. Run the program using: + ```bash go run main.go ``` diff --git a/_examples/actor-helloworld/readme.md b/_examples/actor-helloworld/readme.md index e639a364..412acf09 100644 --- a/_examples/actor-helloworld/readme.md +++ b/_examples/actor-helloworld/readme.md @@ -19,8 +19,7 @@ go get -u github.com/asynkron/protoactor-go ``` ## Running the Example -1. Save the code in a file, named `main.go`, for example. -2. Execute the program with: + ```bash go run main.go ``` diff --git a/_examples/actor-jaegertracing/README.md b/_examples/actor-jaegertracing/README.md index d90db4a3..8c1b8fff 100644 --- a/_examples/actor-jaegertracing/README.md +++ b/_examples/actor-jaegertracing/README.md @@ -21,8 +21,7 @@ go get -u github.com/uber/jaeger-client-go ``` ## Running the Example -1. Save the code in a file, for example, `main.go`. -2. Execute the program: + ```bash go run main.go ``` diff --git a/_examples/actor-lifecycleevents/readme.md b/_examples/actor-lifecycleevents/readme.md index 624c81a8..480cc910 100644 --- a/_examples/actor-lifecycleevents/readme.md +++ b/_examples/actor-lifecycleevents/readme.md @@ -19,8 +19,7 @@ go get -u github.com/asynkron/protoactor-go ``` ## Running the Example -1. Copy the code into a file, named `main.go`, for instance. -2. Run the program: + ```bash go run main.go ``` diff --git a/_examples/actor-logging/main.go b/_examples/actor-logging/main.go index 52fdef92..1a34dccf 100644 --- a/_examples/actor-logging/main.go +++ b/_examples/actor-logging/main.go @@ -23,18 +23,21 @@ func (state *helloActor) Receive(context actor.Context) { } } +// enable JSON logging func jsonLogging(system *actor.ActorSystem) *slog.Logger { return slog.New(slog.NewJSONHandler(os.Stdout, nil)). With("lib", "Proto.Actor"). With("system", system.ID) } +// enable console logging func consoleLogging(system *actor.ActorSystem) *slog.Logger { return slog.Default(). With("lib", "Proto.Actor"). With("system", system.ID) } +// enable colored console logging func coloredConsoleLogging(system *actor.ActorSystem) *slog.Logger { return slog.New(tint.NewHandler(os.Stdout, &tint.Options{ Level: slog.LevelDebug, @@ -44,6 +47,7 @@ func coloredConsoleLogging(system *actor.ActorSystem) *slog.Logger { With("system", system.ID) } +// enable Zap logging func zapAdapterLogging(system *actor.ActorSystem) *slog.Logger { zapLogger, _ := zap.NewProduction() diff --git a/_examples/actor-logging/readme.md b/_examples/actor-logging/readme.md new file mode 100644 index 00000000..1e10e304 --- /dev/null +++ b/_examples/actor-logging/readme.md @@ -0,0 +1,35 @@ +## AI Generated Content. Please report issues + +# Go Example: Advanced Logging with Proto.Actor + +## Introduction +This Go example demonstrates various logging mechanisms within the Proto.Actor framework. It shows how to implement different types of logging, including JSON, console, colored console, and Zap adapter logging. + +## Description +The program creates a simple actor system and uses different logging methods to log a `hello` message. This example is useful for understanding how to implement and customize logging in applications using the Proto.Actor framework, offering insights into structured logging and its benefits. + +## Setup +To run this example, make sure you have: +- Go programming environment +- Proto.Actor for Go +- Necessary logging libraries + +Install the required libraries using: +```bash +go get -u github.com/asynkron/protoactor-go +go get -u github.com/lmittmann/tint +go get -u go.uber.org/zap +``` + +## Running the Example + +```bash +go run main.go +``` + +## Additional Notes +- The example includes different logging functions: `jsonLogging`, `consoleLogging`, `coloredConsoleLogging`, and `zapAdapterLogging`. +- The `helloActor` struct handles a `hello` message and logs it using the specified logging method. +- This example is ideal for developers looking to implement advanced logging techniques in their Go applications using Proto.Actor. + +This example provides a comprehensive demonstration of various logging methods in a Go application using the Proto.Actor framework. diff --git a/_examples/actor-supervision/readme.md b/_examples/actor-supervision/readme.md new file mode 100644 index 00000000..42098761 --- /dev/null +++ b/_examples/actor-supervision/readme.md @@ -0,0 +1,33 @@ +## AI Generated Content. Please report issues + +# Go Example: Actor Supervision with Proto.Actor + +## Introduction +This Go example showcases actor supervision in the Proto.Actor framework. It demonstrates how to handle failures and supervise child actors within a parent actor. + +## Description +The program defines two actor types: `parentActor` and `childActor`. The `parentActor` spawns a `childActor` and sends a message to it. The `childActor` simulates a failure upon receiving the message, triggering the supervision strategy defined in the parent actor. This example is crucial for understanding error handling and supervision in actor-based systems. + +## Setup +Ensure the following are installed to run this example: +- Go programming environment +- Proto.Actor for Go + +Install Proto.Actor with: +```bash +go get -u github.com/asynkron/protoactor-go +``` + +## Running the Example + +```bash +go run main.go +``` + +## Additional Notes +- The `parentActor` is responsible for creating and supervising the `childActor`. +- The `childActor` deliberately causes a panic to demonstrate the supervision mechanism. +- The supervision strategy is defined using `actor.NewOneForOneStrategy`. +- This example is particularly useful for developers looking to implement robust error handling and actor supervision in their Go applications using Proto.Actor. + +This example provides a detailed insight into actor supervision and error handling in a Go application using the Proto.Actor framework.