{"id":19935136,"url":"https://github.com/optimizely/oevents","last_synced_at":"2025-05-03T12:31:06.460Z","repository":{"id":47921521,"uuid":"281806667","full_name":"optimizely/oevents","owner":"optimizely","description":"A CLI for exporting Optimizely Events","archived":true,"fork":false,"pushed_at":"2020-07-29T19:58:01.000Z","size":1872,"stargazers_count":10,"open_issues_count":1,"forks_count":2,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-03-16T13:42:15.367Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/optimizely.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-07-22T23:49:26.000Z","updated_at":"2023-09-28T18:19:53.000Z","dependencies_parsed_at":"2022-08-12T14:10:59.058Z","dependency_job_id":null,"html_url":"https://github.com/optimizely/oevents","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/optimizely%2Foevents","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/optimizely%2Foevents/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/optimizely%2Foevents/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/optimizely%2Foevents/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/optimizely","download_url":"https://codeload.github.com/optimizely/oevents/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252190720,"owners_count":21708938,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-12T23:18:54.417Z","updated_at":"2025-05-03T12:31:05.248Z","avatar_url":"https://github.com/optimizely.png","language":"Shell","readme":"# oevents: A CLI for Optimizely Enriched Event data\n\nOptimizely [Enriched Events Export](https://docs.developers.optimizely.com/optimizely-data/docs/enriched-events-export) gives you secure access to your Optimizely event data so you can analyze your experiment results with greater flexibility. The export includes a useful combination of events attributes:\n\n- Raw metadata (event names, user IDs, etc) that you pass to Optimizely, without additional processing\n- Enriched metadata that Optimizely adds such as experiment IDs, variation IDs, and session IDs\n\nFor more information, see the Enriched Events [data specification](https://docs.developers.optimizely.com/optimizely-data/docs/enriched-events-data-specification).\n\nThis repo contains `oevents`, a simple CLI tool for loading enriched event data.\n\n![oevents demo](./img/demo.gif)\n\n## Prerequisites: bash (v4+), date, jq, curl, and aws\n\n`oevents` is written in [bash](https://www.gnu.org/software/bash/) and should run on OS X and most GNU/Linux distributions.  You'll need to install the following prerequisites:\n\n- [jq](https://stedolan.github.io/jq/)\n- [curl](https://curl.haxx.se/)  (Note: All versions of OS X starting with Jaguar come with curl installed)\n- the [Amazon AWS CLI](https://aws.amazon.com/cli/) (v2+) \n\n## Downloading `oevents`\n\nYou can download a zipped directory containing the `oevents` CLI [from this repo](https://github.com/optimizely/oevents/archive/master.zip) or you can download just the shell script [here](https://library.optimizely.com/data/oevents/latest/oevents)\n\n## Installation \n\n`oevents` is a bash script. To run it, you'll need to make sure it's executable.  Assuming `oevents` is in your working directory, you can do this with the following command:\n\n```sh\n$ chmod +x oevents\n```\n\nTo run `oevents`, you can specify the script's path explicitly like this (again, assuming `oevents` is in your working directory):\n\n```sh\n$ ./oevents help\n```\n\nOr you can add it to a directory in your `PATH` environment variable.  \n\n```sh\n$ sudo cp oevents /usr/local/bin/\n$ oevents help\n```\n\n## Get Help\n\nFor usage instructions, use the `help` command:\n\n```sh\n$ oevents help\n```\n\n## Authenticating\n\nOptimizely Enriched Event data is served via [Amazon S3](https://aws.amazon.com/s3/). `oevents` uses the [Amazon AWS CLI](https://aws.amazon.com/cli/) to interact with S3, which requires authentication.  You can authenticate to AWS in three ways:\n\n1. (Recommended) Pass your [Optimizely Personal Access Token](https://docs.developers.optimizely.com/web/docs/personal-token) to `oevents` via the `OPTIMIZELY_API_TOKEN` environment variable:\n\n    ```sh\n    $ export OPTIMIZELY_API_TOKEN=\u003ctoken\u003e\n    $ oevents ls\n    ```\n2. Pass your [Optimizely Personal Access Token](https://docs.developers.optimizely.com/web/docs/personal-token) and [Optimizely Account ID](https://help.optimizely.com/Account_Settings/Account_name%2C_ID%2C_and_multi-account_login_in_Optimizely_X) via the `--token` and `--account-id` command line arguments:\n\n    ```sh\n    $ oevents ls --token \u003ctoken\u003e --account-id 12345\n    ```\n3. Provide your AWS credentials directly. See the [AWS user guide](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html) for instructions.\n\n**Note:** If you chose methods 1 or 2, `oevents` will acquire temporary AWS credentials using the [Optimizely Authentication API](https://docs.developers.optimizely.com/optimizely-data/docs/authentication-api). You can use the `oevents auth` command to display those credentials or write them to a file.  This is handy if you prefer to access Enriched Event by some other means (e.g. using the AWS CLI directly, or [boto3](https://aws.amazon.com/sdk-for-python/)):\n\n```sh\n  $ oevents auth --token \u003coptimizely personal access token\u003e\n\n  export AWS_ACCESS_KEY_ID=\u003ckey id\u003e\n  export AWS_SECRET_ACCESS_KEY=\u003csecret access key\u003e\n  export AWS_SESSION_TOKEN=\u003csession token\u003e\n  export AWS_SESSION_EXPIRATION=1594953226000\n  export S3_BASE_PATH=s3://optimizely-events-data/v1/account_id=12345/\n```\n\n## Exploring your Enriched Event data\n\n[decisions]: https://docs.developers.optimizely.com/web/docs/enriched-events-export#section-decisions\n[conversions]: https://docs.developers.optimizely.com/web/docs/enriched-events-export#section-conversions\n\nEnriched Events are partitioned into two top-level datasets, [decisions] (`type=decisions`) and [conversions] (`type=events`).  Each of these datasets is partitioned by date and experiment (for decisions) or event type (for conversions).  \n\nYou can use `oevents ls` to list all of the experiments that produced decision data on a given date:\n\n```sh\n$ oevents ls --type decisions --date 2020-05-10\n\n                           PRE experiment=10676850402/\n                           PRE experiment=14386840295/\n                           PRE experiment=14821050982/\n                           PRE experiment=15117030650/\n                           PRE experiment=17517981213/\n                           PRE experiment=17535310125/\n                           PRE experiment=8997901009/\n```\n\nYou can also use `oevents` to list all of the event types collected on a given day:\n\n```sh\n$ oevents ls --type events --date 2020-05-10\n\n                           PRE event=search_query/\n                           PRE event=search_results_click/\n                           PRE event=add_to_cart/\n                           PRE event=purchase/\n```\n\n## Downloading your Enriched Event data\n\nYou can use `oevents load` to download your Enriched Event data in [Apache Parquet](https://parquet.apache.org/) format.  Command line arguments can be used to specify a progressively narrower subset of your data.\n\nThe following command will download *all* enriched event data associated with your Optimizely account.  Data will be downloaded into the current working directory. You can configure the destination using the `--output` command line argument or the `OPTIMIZELY_DATA_DIR` environment variable.\n\n```sh\n$ oevents load\n```\n\nUse the `--type` argument to specify [decisions] or [events][conversions]  The following will download all [decision][decisions] data associated with your Optimizely account:\n\n```sh\n$ oevents load \\\n    --type decisions\n```\n\nThe following will download all [decision][decisions] data collected between July 1st and 5th, 2020 (inclusive):\n\n```sh\n$ oevents load \\\n    --type decisions \\\n    --start 2020-07-01 \\\n    --end 2020-07-05\n```\n\nThe following will download all [decision][decisions] data for experiment `12345` collected between July 1st and 5th, 2020:\n\n```sh\n$ oevents load \\\n    --type decisions \\\n    --start 2020-07-01 \\\n    --end 2020-07-05 \\\n    --experiment 12345\n```\n\nThe following will download all [conversion][conversions] data for event `add_to_cart` collected between July 1st and 5th, 2020:\n\n```sh\n$ oevents load \\\n    --type events \\\n    --start 2020-07-01 \\\n    --end 2020-07-05 \\\n    --event add_to_cart\n```\n\n## Testing `oevents`\n\nYou can run the `oevents` test suite by installing [BATS](https://github.com/bats-core/bats-core) and running `test.bats` in this directory.  Note: the `oevents` test suite requires bash v4.4+.\n\n\n## Acknowledgements\n\nThis software depends on code from the following wonderful open source projects:\n\n#### aws-cli\nCopyright (c) 2012-2020 Amazon.com, Inc. or its affiliates.\n[License (Apache 2.0)](https://github.com/aws/aws-cli/blob/develop/LICENSE.txt)\n\n#### jq\nCopyright (c) 2012 Stephen Dolan.\n[License (MIT)](https://github.com/stedolan/jq/blob/master/COPYING)\n\n#### curl\nCopyright (c) 1996 - 2020, Daniel Stenberg, daniel@haxx.se, and many\ncontributors.\n[License (MIT)](https://github.com/curl/curl/blob/master/COPYING)\n\n#### bats-core\nCopyright (c) 2014 Sam Stephenson\n[License (MIT)](https://github.com/bats-core/bats-core/blob/master/LICENSE.md)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foptimizely%2Foevents","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foptimizely%2Foevents","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foptimizely%2Foevents/lists"}