Skip to main content

Impression Server

You can manipulate your feature's outputs in the UI at this point, but they won't actually show up on your getting started site until you start an impression server.

The impression server is the Causal component that handles all the low-latency communication between your servers and Causal. You can spin one up in or near your data center servers using a Docker image.

Managed impression servers are currently not self served. If you are interested in a managed solution, please email support@causallabs.io. We will need to know your cloud provider and the datacenter that has the least latency to your systems.

The following sections are only relevant if you are setting up an impression server on your own infrastructure. If you are using a managed impression server, skip to the next section once you get your impression server URL from Causal support.

Docker​

You can spin up an Impression server using the standard Docker image.

The impression server writes data to the cloud provider that you specified in Backend Setup. If your back end is on AWS, you must provide the following credentials to your docker container:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "S3",
            "Effect": "Allow",
            "Action": [
                "s3:PutObject",
                "s3:GetObject",
                "s3:ListBucket",
                "s3:DeleteObject"
            ],
            "Resource": [
                "arn:aws:s3:::bucket_name/*",
                "arn:aws:s3:::bucket_name"
            ]
        }
    ]
}

If your impression server is writing to Azure, it will download the required credentials from your Causal configuration, and nothing extra needs to be done.

Each time the impression server starts, it does a test write to your storage in order to insure that everything is hooked up properly.

For AWS, the impression server uses the AWS Default Credential Provider Chain, so you can use any of those techniques to authorize the Impression Server.

In the following example simply starts an impression server using Docker Desktop and the AWS credentials stored in the .aws directory in your account:

$ docker run -p 3004:3004 -e AWS_PROFILE -v ~/.aws:/root/.aws causallabs/iserver:0.47.0 --token <security token> --environment <environment>

Note that the impression server, by default, listens on port 3004. You can change the port using the --port startup option.

You can get a list of all startup options as follows:

$ docker run causallabs/iserver:0.47.0 --help

ECS Notes​

It's pretty easy to get the Causal impression server running on an ECS cluster in AWS. The following are general notes on how to get it done. Please reach out to support@causallabs.io if you feel something needs to be added here.

  1. Create a new task definition for the impression server.
  • Name the container something appropriate (ie iserver-environment_name), and set the image URI to the public Causal iserver image, currently causallabs/iserver:0.44.0
  • Add a port mapping to expose port 3004 (or another if you choose to run on a different port). The protocol is TCP and the App Protocol is HTTP.
  • Create a Task Role (not Task Execution Role) that has the above AWS permissions. Make sure that you set the "Trusted Entity Type" to "AWS service", and the "Use Case" to "Elastic Container Service Task".
  • Add the appropriate impression server startup arguments to the docker configuration. You'll need to at least add the environment ID for the impression server and the security token. So, under the 'Command' field, add: --token,your_token,--environment,your_environment. You can leave the 'Entry Point' field blank.
  1. Deploy the task: Deploy -> Create Service
  • Under "Deployment Configuration" the number of tasks should be 1. If you need more, you'll have to set up sticky sessions.
  • Under "Networking", add an additional security group that will allow the service's load balancer to be accessed from the internet.
  • Under "Load Balancing" pick an Application Load Balancer, and set the health check path to '/iserver/nsessions'

Once your load balancer is up you should be able to point your browser http://load_balancer_address/iserver/nsessions and get back the response "0". (because I'm assuming there are no sessions on your impression server yet)

Environment Variables​

In addition to the AWS environment variables supported in the default credential provider chain, the impression server image understands the following:

  • ISERVER_JARS: a set of colon separated jar files that are added to the impression server's CLASSPATH. This is useful for including support jars for java plugins or instrumentation code.

OpenTelemetry Instrumentation​

The impression server codebase is instrumented with the OpenTelemetry https://opentelemetry.io/ API to give insights into your running instance. The Impression Server Metrics measured are listed here. Also, a trace is started for every HTTP request into the impression server.

The docker image is bundled with the OpenTelemetry agent used to send data to any APM (Application Performance Monitoring) platform supporting the OpenTelemetry spec. The agent activates and instruments the process if the OPENTELEMETRY_OPERATOR_PORT env variable is present. Please consult with your AMP provider for how to configure and deploy the open telemetry collector into your environment.

The agent is configured through environmental variables. The full list of possible configurable environment variables is described here: https://opentelemetry.io/docs/instrumentation/java/automatic/agent-config/. This table below lists the standard variables we recommend setting.

NameDescriptionExample Value
OTEL_RESOURCE_ATTRIBUTESAdditional tags you would like to attach to each metric or trace.cluster_name=production
OTEL_EXPORTER_OTLP_COMPRESSIONCompress the output before sending to the AMP service.gzip
OTEL_EXPORTER_OTLP_ENDPOINTThe address of the OTEL Collector that is running in your cluster.http://<otel-collector-address>:4317
OTEL_SERVICE_NAMEThe name of the service.iserver