The Actor Runtime Manager

This document covers installing and deploying the Actor Runtime, using the Actor Runtime Manager to deploy or stop actors, and setup for an Actor Application VS project template.

The Actor Runtime is an execution fabric that designed for highly available actor services, allowing for multiple service replicas and providing data replication functionality and fail-over logic. When you launch an actor service, you launch it to the Actor Runtime.

The Actor Runtime works in terms of actor applications and actor services. An actor application can be thought of as the logic for a service. An actor service is an instance of an actor application. These are the actor applications provided “out-of-the-box” with this release:

  • EmptyActorApp: This actor application allows you to launch “empty” actor services, which are actor services with no built-in intelligence. Intelligence can be provided to these actors by transferring ActorMethod-containing assemblies to them.
  • ListActorApp: This actor application allows you to launch list actor services, which are actor services that have built-in intelligence for supporting list operations.
  • DictionaryActorApp: This actor application allows you to launch dictionary actor services, which have built-in intelligence for key-value store operations.
  • StatelessActorApp: Actually a misnomer; this application’s services can indeed hold state, but the persistence of that state is managed outside of the Actor Runtime. So from the Actor Runtime’s perspective, the services from this app are stateless. This application and its associated services are the first step in providing storage mechanisms for ActorFx outside the Actor Runtime.

The Actor Runtime Manager is an application that, as you might guess, allows you to manage the Actor Runtime. The provided functionality includes installing the Actor Runtime software, deploying and bringing down an Actor Runtime cluster, deploying and un-deploying actor applications on an Actor Runtime cluster, and deploying and killing actor services.

This document contains instructions and information pertaining to the installation and operation of the Actor Runtime Manager.

Installing the Actor Runtime Manager

The Actor Runtime Manager is installed as part of the Actor Framework, which is installed by running ActorFramework.msi. The prerequisites for installing the Actor Framework and using the Actor Runtime Manager are as follows:

  • 64-bit OS
  • Windows 7 or above
  • .NET Framework 4.5
  • Windows Azure SDK 1.8 (October 2012)

Starting the Actor Runtime Manager

When the Actor Framework is installed, an Administrator-mode shortcut to the Actor Runtime Manager is created on the desktop. Double-click that shortcut, and the Actor Runtime Manager should pop up.

Installing the Actor Runtime Software

The first time that you start up the Actor Runtime Manager, it will look like this:

image

Before you do anything else, you need to install the Actor Runtime software. Do so by pressing the “Install” button. This results in running the .msi file associated with the Actor Runtime, and the ensuing process is mostly self-explanatory. When the installation is near completion, though, there are some specific directions that you need to follow:

  • Windows’ “Services” Control Panel is popped up, along with this message from the installer:

 clip_image003

Follow those instructions. Note that if you change your password, you’ll need to re-enter your new password. Go to the Services Control Panel (Start -> Run -> Services, or type services.msc at a command prompt), find the “Windows Fabric Host Service”, open Properties then enter your new password.

  • When you follow the instructions and then shut down the “Services” Control Panel and the “Special Instructions” popup, you will see another popup:

 clip_image004

Do as the pop-up says – press “OK”, log out, log back in, and re-launch the ActorRuntimeManager.

Deploying the Actor Runtime Cluster

Once the Actor Runtime Software is installed, and you re-launch the Actor Runtime Manager, it should look like this:

image

The “Scour” button was added in release 0.2, and it can come in handy when you upgrade your Actor Runtime. The purpose of the “Scour” button is to erase all traces of Actor software from your Actor Runtime cluster. The cluster should be “scoured” either just before installing an Actor Runtime update or just after doing so; without performing a scour, it is possible that the ActorRuntime will get confused between some leftover bits from the old version and new bits from the new version. And note that, in order for the “Scour” to be effective, you need to have stopped all actors and un-deployed all actor apps before running the “Scour”. Also notice that the “Scour” button is only enabled when the cluster is spun down.

Note further the addition of connection mode and connection string information to our UI in version 0.2. We are part of the way through enabling users to change the mode from “Local” to “Cloud”; once we have that fully supported, we will enable the “Change” button.

To “spin up” a simulated local[1] Actor Runtime cluster, press the “Deploy” button. Upon doing so, you should notice that five command prompt windows are popped up, looking something like this:

clip_image007

and your Actor Runtime Manager screen should indicate that the cluster has been deployed but is not yet accepting connections:

image

You will need to wait a while (between 1 and 5 minutes) as the cluster spins up and readies itself for Actor operations. Once the cluster is ready, you see that the Actor Runtime Manager screen now indicates that the cluster is deployed and connected:

image

At this point, you can launch actor applications.

To un-deploy the Actor Runtime Cluster, press the “Undeploy” button (which used to be the “Deploy” button). Note that any actor applications and actor services that are deployed at the time that you take down the Actor Runtime Cluster will be brought back up the next time that you bring up the cluster.

Deploying Actor Applications

Pressing the “DeployActorApp…” button will result in a dialog being popped up:

clip_image012

Choose which type of Actor Application (ListActorApp, EmptyActorApp, DictionaryActorApp or StatelessActorApp) to deploy, and then hit the “Deploy” button. The dialog will briefly stay up and give information about the progress of the deployment. When it pops down, five more command prompts will be popped up for the chosen application, each of which should look something like this:

clip_image014

When the deployment of the Actor Application is complete, its existence will be noted in the Actor Runtime Manager window:

image

To un-deploy an actor application, check it’s entry in the “Deployed Actor Apps” list and press the “Undeploy Checked Apps” button. Note that it’s good form to first stop all actor services associated with an actor application before un-deploying the actor application.

Launching Actor Services

To launch an actor service, check exactly one item in the “Deployed Actor Apps” list, then press the “Launch Checked App Actor …” button. A dialog will then pop up asking some specifics about the soon-to-be-started service. The dialog’s appearance is based upon whether the desired service is stateful (fabric:/actor/list, fabric:/actor/adhoc or fabric:/actor/dictionary apps) or stateless (fabric:/actor/stateless app).

For stateful apps, you can specify the name of the new actor (not the full path name, just the simple name), as well as the desired number of replicas:

clip_image001

For stateless apps, the dialog looks like this:

clip_image002

For stateless apps, then, you get to specify:

  • The simple name of the actor
  • The actor’s “personality” (“Empty”, “List” or “Dictionary”)
  • The actor’s state type (currently only “InMemory” is allowed, but soon we hope to support “SQLAzure” and “AzureTables”)

Stopping Actor Services

To stop an actor service, check its entry in the “Running Actors” list and then press the “Stop Checked Actors” button. It is legal to take down multiple services at once. Note that though the resulting operation may appear to be nearly instantaneous, it may take some time for the actor service to be fully brought down.

Development Environment

Setup

After installing the Actor Runtime Manager and deploying an actor, you’ll want to create a VS project that interacts with the actor. We have provided a VS project template. Install it like this:

  • Create the following directory on your machine:

“C:\Users\%USERNAME%\Documents\Visual Studio 2012\Templates\ProjectTemplates\Visual C#\Cloud”

  • Copy the Actor Application.zip to the directory above.
  • Launch VS2012.
  • Create a new project. Look in Visual C# -> Cloud for a template called “Actor Application”, like this:

clip_image018

  • Choose that template and call your new project whatever you like.
  • If the Actor Runtime is running, and you have deployed the “EmptyActorApp” from the Actor Runtime Manager, then you should be able to run the project.

From there, feel free to tweak the application as you see fit, changing the behavior of the provided actor methods or adding some of your own. The possibilities are endless!

Current Limitations

In our initial release, all client applications must target x64. Our intention is to support compilation on other platforms in the future via .NET portable libraries, and eventually Javascript as well.

Actors cannot currently be accessed from Windows Store applications. This is a limitation of the Actor Runtime that we intend to fix over time.

 

Tooling

There are a couple of tools available for actor developers that come with the release. They are located in the application installation directory (“C:\Program Files (x86)\MSOpenTech\Actor Framework” on most boxes).

ActorDirectClient

ActorDirectClient is a command-line application that allows you to connect to an actor and then call actor methods on that actor. By default, ActorDirectClient connects to the Actor Runtime cluster at 127.0.0.1:9000 (i.e., the local development cluster on your machine). If you would like it to connect to some other Actor Runtime cluster (e.g., yourCloudService.cloudapp.net:9000), then run ActorClientDirect from the command line and pass the desired connection string as a parameter.

When the ActorDirectClient first comes up, you see something like this:

Welcome to the Direct Actor Client

0: fabric:/actor/adhoc

1: fabric:/actor/adhoc/EmptyDeployer

2: fabric:/actor/gateway

3: fabric:/actor/gateway/RequiredGatewayService

4: fabric:/actor/list

5: fabric:/actor/list/ListDeployer

6: fabric:/actor/list/demo_ListA

7: fabric:/actor/list/demo_ListB

8: fabric:/actor/list/demo_mainList

To which actor would you like to connect?

Choose your desired actor (make sure to choose an actor, not an application), and hit return. You are then asked:

Would you like to use a Gateway Service to connect to the Windows Fabric Service?

Windows Gateway Service enables users to use Windows Fabric Services running in

Azure from outside of Azure

[y]es

[n]o

Enter ‘y’ if you are connecting to a service running on Azure, ‘n’ if you are connecting to a service running locally in a development environment.

After that, you can call actor methods on your chosen actor, where the first entry on the line is the name of the actor method and the remaining entries are parameters for that method, and get results back:

Enter method and parameters: Length ListDeployer

Result: 6

Enter method and parameters: Enumerate ListDeployer 0 -1

Result: [

"m2",

"m1",

"zero",

"one",

"two",

"three"

]

Note that all parameters are passed to the chosen actor as strings, so the actor methods called must be able to accept string parameters.

In addition to calling actor methods, there are some other special-purpose commands that can be useful for testing:

  • “AddAssembly”: Ships the current assembly (i.e., ActorDirectClient.exe) over to your actor. You should then be able to call some actor methods defined within the assembly, like SayHello.
  • “SUBSCRIBE <eventType>”: Requests that the actor publish all events of type <eventType> to this client. You will then be notified each time that such an event type is received.
  • “UNSUBSCRIBE <eventType”: Requests that the actor cease publishing events of type <eventType> to this client.
  • “TIME <iterations> <command>”: Allows you to time how long it takes for <iterations> repetitions of <command> to complete. Sample usage:

        TIME 1000 Push ListDeployer right xxx

The example above runs “Push ListDeployer right xxx” 1000 times, and tells you how long it took to do so.

ActorAnalyzer

Actors produce ETW information for certain events. The ActorAnalyzer is a GUI application that allows you to connect to one or more actors and see the recent ETW history on that actor, as well as monitor newly emitted ETW events in real time.

The ActorAnalyzer looks like this when it first comes up:

clip_image002

Make sure that the “Fabric Address” matches the Actor Runtime cluster that contains your actor (by default, it points to a local development cluster), and then press the “Connect to Actor…” button. You see a list of available actors to monitor (in this case, only one):

clip_image003[1]

Choose the desired actor and press “Select”. You return to the main GUI, which should now have a tabbed pane with events from your chosen actor:

clip_image005

This pane will be updated in real time as new actor events are emitted.  If you so desire, you can proceed to connect to other actors and have multiple panes showing.

Note that, as of the 0.5 release, the following ETW events are produced by actors:

Event

Description

Level

AddAssembly

Emitted every time that an assembly is added to an actor.

Informational

DuplicateAssemblyReceived

Signifies that an AddAssembly operation sent over an assembly that was already stored on the actor.

Informational

AssemblyLoadFailure

Signifies that one or more types failed to load while ingesting an assembly.

Warning

ActorMethodSignatureFailure

Signifies that an actor method within an assembly was rejected due to having an unrecognized signature.

Error

ActorMethodsLoaded

Signifies that actor methods were successfully loaded as part of an assembly.

Informational

ActorMethodsUnloaded

Signifies that stale actor methods were unloaded as part of an AddAssembly operation.

Informational

ActorMethodCompleted

Signifies that an actor method has successfully been called.

Verbose

AssemblyHasNoActorMethods

Signified that an AddAssembly operation completed without adding any actor methods.

Warning

ActorMethodError

Signifies that an actor method call was unsuccessful.

Error

EventPublished

Signifies that an actor has published an event.

Verbose

EventReceived

Signifies that an actor has received an event from another actor.

Verbose

SubscriptionRequestSent

Signifies that an actor has submitted a subscription request to another actor.

Informational

SubscriptionRequestReceived

Signifies that an actor has received a subscription request from another actor or a client.

Informational

Also note that, since our default filter for ETW events is “Informational”, you should never see any ActorMethodCompleted events (or any other events emitted at “Verbose” level).

Finally, please take note that we plan on expanding ETW coverage in the future so that the data obtainable through this tool is richer and more informative.


[1] Our aim is to have production Azure cluster support built into the Actor Runtime Manager very soon.

Last edited Jun 5, 2013 at 7:35 PM by joehoag, version 9

Comments

darrellt May 25, 2013 at 10:19 PM 
This is fantastic news and just what we need to drive our Knowledge Management tools and systems.

Thanks for all that you do Microsoft!

Tavi