为了支持Spark REPL功能，阿里云数据湖分析团队推出了本地安装Jupyter Lab和DLA Proxy、使用Docker快速启动环境两种方案，帮助用户将本地Jupyter Lab和阿里云DLA Spark连接在一起，从而可以利用DLA的弹性资源进行交互测试和计算。

注意事项

  • DLA Spark当前支持python3，Scala 2.11的Jupyter可交互作业。
  • 新版Jupyter Lab对Python的最低版本要求是Python 3.6。
  • 推荐使用Docker快速启动环境方式来使用本功能。
  • 交互式作业会在空闲一段时间后自动释放，默认释放时间为最后一个代码块执行完毕后1200秒。用户可以通过spark.dla.session.ttl来配置空闲多长时间后自动释放交互式作业。

本地安装Jupyter Lab和DLA Proxy

  1. 安装DLA Livy Proxy。
    1. 安装Aliyun OpenAPI SDK。
      说明 Aliyun OpenAPI SDK的最低版本要求是2.0.4。
    2. 使用以下命令安装Aliyun DLA Livy Proxy。
      pip install aliyun-dla-livy-proxy-0.0.5.zip
      说明 您需要使用root用户安装Aliyun DLA Livy Proxy，非root用户进行安装可能无法注册命令到可执行目录中。Aliyun DLA Livy Proxy安装完成后，您可以在命令行中找到dlaproxy命令。
    3. 启动DLA Livy Proxy。
      DLA Livy Proxy用于将阿里云DLA的接口翻译为SparkMagic需要的Apache Livy语义接口，从而在本地建立HTTP PROXY监听与转发，端口默认是5000。 
      # 查看dlaproxy命令使用方式。
$dlaproxy -h
usage: dlaproxy [-h] --vcname VCNAME -i AK -k SECRET --region REGION [--host HOST] [--port PORT] [--loglevel LOGLEVEL]

Proxy AliYun DLA as Livy

optional arguments:
  -h, --help            show this help message and exit
  --vcname VCNAME       Virtual Cluster Name
  -i AK, --access-key-id AK
                        Aliyun Access Key Id
  -k SECRET, --access-key-secret SECRET
                        Aliyun Access Key Secret
  --region REGION       Aliyun Region Id
  --host HOST           Proxy Host Ip
  --port PORT           Proxy Host Port
  --loglevel LOGLEVEL   python standard log level
  
# 直接启动dla livy proxy。
dlaproxy --vcname <vcname> -i akid -k aksec --region <regionid>

      上述代码中出现的输入参数说明如下：

      参数名称 参数说明
      --vcname DLA Spark虚拟集群名称。
      说明 您可以登录Data Lake Analytics控制台，在虚拟集群管理 > 集群名称/实例ID > 详情中查看虚拟集群名称。
      -i RAM用户的AccessKey ID。
      说明 如果您已经创建了AccessKey，可以在RAM控制台上查看相关信息。关于如何查看以及创建AccessKey，请参见为RAM用户创建访问密钥。
      -k RAM用户的AccessKey Secret。
      说明 如果您已经创建了AccessKey，可以在RAM控制台上查看相关信息。关于如何查看以及创建AccessKey，请参见为RAM用户创建访问密钥。
      --region DLA所在地域对应的Region ID，详细信息请参见地域和可用区。
      --host 服务绑定的Host，默认为127.0.0.1， 仅代理本地请求。可以修改为0.0.0.0或者其它地址监听公网/内网的请求并代理，建议使用默认值。
      --port 监听端口， 默认为5000， 可以修改为其它端口，建议使用默认值。
      --loglevel 日志级别， 默认为INFO，可以修改为ERROR、 WARNING、 INFO或DEBUG，建议使用默认值。
  2. 安装Jupyter Lab。
    1. 可选：安装venv。
      说明 推荐将整套环境安装到Virtual Environment环境中，这样后续的安装不会破坏主账号下的公共Python环境。
    2. 使用以下命令安装Jupyter lab。
      pip install jupyterlab #安装Jupyter Lab。
jupyter lab  #验证一下是否安装成功, 成功安装的话, 可以看到启动日志。
    3. 按照如下步骤安装Sparkmagic。
      1. 安装库。
         pip install sparkmagic
      2. 确保ipywidgets成功运行。
         jupyter nbextension enable --py --sys-prefix widgetsnbextension
      3. 如果您使用的是JupyterLab，需要运行如下命令。
         jupyter labextension install "@jupyter-widgets/jupyterlab-manager"
      4. 使用pip show sparkmagic找到对应的文件夹，进入文件夹执行如下命令安装kernels。
         jupyter-kernelspec install sparkmagic/kernels/sparkkernel
 jupyter-kernelspec install sparkmagic/kernels/pysparkkernel
 jupyter-kernelspec install sparkmagic/kernels/sparkrkernel
      5. 修改~/.sparkmagic/config.json上的配置文件，详情请参见example_config.json。
      6. 运行。
         jupyter serverextension enable --py sparkmagic
    安装成功后，需要手动创建配置文件~/.sparkmagic/config.json，并将url的配置指向本地开启的代理。示例如下：
    {
  "kernel_python_credentials" : {
    "username": "",
    "password": "",
    "url": "http://127.0.0.1:5000",
    "auth": "None"
  },

  "kernel_scala_credentials" : {
    "username": "",
    "password": "",
    "url": " http://127.0.0.1:5000",
    "auth": "None"
  },
  "kernel_r_credentials": {
    "username": "",
    "password": "",
    "url": "http://localhost:5000"
  },

  "logging_config": {
    "version": 1,
    "formatters": {
      "magicsFormatter": { 
        "format": "%(asctime)s\t%(levelname)s\t%(message)s",
        "datefmt": ""
      }
    },
    "handlers": {
      "magicsHandler": { 
        "class": "hdijupyterutils.filehandler.MagicsFileHandler",
        "formatter": "magicsFormatter",
        "home_path": "~/.sparkmagic"
      }
    },
    "loggers": {
      "magicsLogger": { 
        "handlers": ["magicsHandler"],
        "level": "DEBUG",
        "propagate": 0
      }
    }
  },

  "wait_for_idle_timeout_seconds": 15,
  "livy_session_startup_timeout_seconds": 600,

  "fatal_error_suggestion": "The code failed because of a fatal error:\n\t{}.\n\nSome things to try:\na) Make sure Spark has enough available resources for Jupyter to create a Spark context.\nb) Contact your Jupyter administrator to make sure the Spark magics library is configured correctly.\nc) Restart the kernel.",

  "ignore_ssl_errors": false,

  "session_configs": {
    "conf": {
      "spark.dla.connectors": "oss"
    }
  },

  "use_auto_viz": true,
  "coerce_dataframe": true,
  "max_results_sql": 2500,
  "pyspark_dataframe_encoding": "utf-8",
  
  "heartbeat_refresh_seconds": 30,
  "livy_server_heartbeat_timeout_seconds": 0,
  "heartbeat_retry_seconds": 10,

  "server_extension_default_kernel_name": "pysparkkernel",
  "custom_headers": {},
  
  "retry_policy": "configurable",
  "retry_seconds_to_sleep_list": [0.2, 0.5, 1, 3, 5],
  "configurable_retry_policy_max_retries": 8
}
    说明 示例中的session_configs是提交到DLA Spark的conf部分，如果需要加载JAR包，连接DLA的元数据服务请参考作业配置指南。
    DLA Livy Proxy启动后监听的默认地址为127.0.0.1:5000，如果在启动DLA Livy Proxy时修改了默认的Host和Port， 则需要修改上述配置文件中的url部分。示例：启动时指定地址 --host 192.168.1.3 --port 8080， 则应当将上述配置文件中的url为http://192.168.1.3:8080，修改后如下所示： 
    { 
  "kernel_python_credentials" : {
    "username": "",
    "password": "",
    "url": "http://192.168.1.3:8080",
    "auth": "None"
  },
  "kernel_scala_credentials" : {
    "username": "",
    "password": "",
    "url": "http://192.168.1.3:8080",
    "auth": "None"
  },
  "kernel_r_credentials": {
    "username": "",
    "password": "",
    "url": "http://192.168.1.3:8080"
  },
 "logging_config": {
    "version": 1,
    "formatters": {
      "magicsFormatter": { 
        "format": "%(asctime)s\t%(levelname)s\t%(message)s",
        "datefmt": ""
      }
    },
    "handlers": {
      "magicsHandler": { 
        "class": "hdijupyterutils.filehandler.MagicsFileHandler",
        "formatter": "magicsFormatter",
        "home_path": "~/.sparkmagic"
      }
    },
    "loggers": {
      "magicsLogger": { 
        "handlers": ["magicsHandler"],
        "level": "DEBUG",
        "propagate": 0
      }
    }
  },

  "wait_for_idle_timeout_seconds": 15,
  "livy_session_startup_timeout_seconds": 600,

  "fatal_error_suggestion": "The code failed because of a fatal error:\n\t{}.\n\nSome things to try:\na) Make sure Spark has enough available resources for Jupyter to create a Spark context.\nb) Contact your Jupyter administrator to make sure the Spark magics library is configured correctly.\nc) Restart the kernel.",

  "ignore_ssl_errors": false,

  "session_configs": {
    "conf": {
      "spark.dla.connectors": "oss"
    }
  },

  "use_auto_viz": true,
  "coerce_dataframe": true,
  "max_results_sql": 2500,
  "pyspark_dataframe_encoding": "utf-8",
  
  "heartbeat_refresh_seconds": 30,
  "livy_server_heartbeat_timeout_seconds": 0,
  "heartbeat_retry_seconds": 10,

  "server_extension_default_kernel_name": "pysparkkernel",
  "custom_headers": {},
  
  "retry_policy": "configurable",
  "retry_seconds_to_sleep_list": [0.2, 0.5, 1, 3, 5],
  "configurable_retry_policy_max_retries": 8
}
  3. 运行Jupyter Lab。
    # 重新启动Jupyter Lab。
jupyter lab

# 启动DLA Livy Proxy。
dlaproxy --vcname vcname -i akid -k aksec --region <regionid>
    Jupyter Lab启动日志中会打印Jupyter Lab的本地地址。如下图所示：日志打印
    当系统出现提示Aliyun DLA Proxy is ready，表明DLA Livy Proxy启动成功。DLA Livy Proxy启动成功后，您就可以正常使用Jupyter Lab了。Jupyter Lab的使用文档，请参考jupyterlab官方地址。
    运行Jupyter Lab任务，DLA中会自动创建DLA Spark作业，您可以登录Data Lake Analytics控制台，在Serverless Spark > 作业管理菜单进行查看和管理。如下图所示，名称以notebook_为开头的Spark作业即为Jupyter交互式作业。作业管理
    当Jupyter Lab运行起来后，您仍然可以动态的修改配置，修改方式是在Jupyter Lab代码单元中使用magic语句来覆盖旧的配置项。执行后，Jupyter Lab会根据新的配置项重启作业。
    # 重新启动Jupyter Lab。
jupyter lab
# 启动DLA Livy Proxy。
dlaproxy --vcname vcname -i akid -k aksec --region <regionid>
    %%configure -f
{ 
    "conf": {
      "spark.sql.hive.metastore.version": "dla",
      "spark.dla.connectors": "oss"
    }
}
    如果需要使用自制的依赖方法，您可以参考下述配置。
    %%configure -f
{ 
    "conf": {
      ...
    },
    "pyFiles": "oss://{your bucket name}/{path}/*.zip" # module
}
  4. 关闭Jupyter Lab作业。

    单击JupyterLab Kernel菜单栏下的Restart Kernel。

使用Docker快速启动环境

阿里云数据湖团队同时提供Docker镜像快速启动一个Jupyter交互式开发环境，Docker的安装和使用说明请参见Docker官方文档。

  1. 安装并启动Docker后，使用如下命令拉取DLA Jupyter镜像。
    docker pull registry.cn-hangzhou.aliyuncs.com/dla_spark/dla-jupyter:0.5
  2. 拉取成功后，您可以使用如下命令查看此镜像的帮助文件。
    docker run -ti registry.cn-hangzhou.aliyuncs.com/dla_spark/dla-jupyter:0.5

Used to run jupyter lab for Aliyun DLA 
Usage example: docker run -it -p 8888:8888 dla-jupyter:0.1 -i akid -k aksec -r cn-hanghzou -c spark-vc -l INFO 
    -i Aliyun AkId
    -k Aliyun AkSec
    -r Aliyun Region Id
    -c Aliyun DLA Virtual cluster name
    -l LogLevel
    上述代码中出现的参数和DLA Proxy的参数非常相似，具体说明如下。
    参数名称 参数说明
    -c DLA Spark虚拟集群名称。
    说明 您可以登录Data Lake Analytics控制台。在虚拟集群管理 > 集群名称/实例ID > 详情中查看虚拟集群名称。
    -i RAM用户的AccessKey ID。
    说明 如果您已经创建了AccessKey，可以在RAM控制台上查看相关信息。关于如何查看以及创建AccessKey，请参见为RAM用户创建访问密钥。
    -k RAM用户的AccessKey Secret。
    说明 如果您已经创建了AccessKey，可以在RAM控制台上查看相关信息。关于如何查看以及创建AccessKey，请参见为RAM用户创建访问密钥。
    -r DLA所在地域对应的Region ID，详细信息请参见地域和可用区。
    -l 日志级别，默认为INFO，可以修改为ERROR、 WARNING、 INFO或DEBUG，建议使用默认值。
  3. 输入正确的参数，在本地启动对应的实例。
     docker run -it -p 8888:8888 registry.cn-hangzhou.aliyuncs.com/dla_spark/dla-jupyter:0.5 -i {AkId} -k {AkSec} -r {RegionId} -c {VcName}
    启动成功后您可以看到如下图所示的提示信息，将标注框中的网址贴入浏览器可开始使用Jupyter服务直连DLA Spark。启动成功
注意事项
  • 在排查错误时需要观察底层日志，文件浏览框中的dlaproxy.log即为日志记录文件，正确的启动信息如下图所示。启动信息
  • 在不挂载宿主机文件夹的情况下，关闭Docker后编辑的文件会丢失。Docker关闭时也会自动尝试终止所有正在运行的Spark交互式作业。此时，您可以选择如下两种方案。
    • 在关闭Docker前保证所有的文件被妥善的复制保管。
    • 将本地文件夹挂载到Docker镜像中，并将作业文件存储在对应的文件夹下。

      以Linux环境为例，将文件夹/home/admin/notebook挂载到Docker实例/root/notebook文件夹下，启动命令如下。 

       docker run -it --privileged=true -p 8888:8888  -v /home/admin/notebook:/root/notebook registry.cn-hangzhou.aliyuncs.com/dla_spark/dla-jupyter:0.5 -i {AkId} -k {AkSec} -r {RegionId} -c {VcName}

      需要注意将编辑中的notebook最终另存到/tmp，关闭Docker示例后，在宿主机的/home/admin/notebook文件夹下可以看到对应的文件，下次启动Docker实例时可以接着工作。

      说明 更多信息，请参见 Docker卷管理文档。

常见问题处理

  • 问题现象：Jupyter Lab启动失败，出现如下报错，如何处理？
    • [C 09:53:15.840 LabApp] Bad config encountered during initialization:
    • [C 09:53:15.840 LabApp] Could not decode '\xe6\x9c\xaa\xe5\x91\xbd\xe5\x90\x8d' for unicode trait 'untitled_notebook' of a LargeFileManager instance.

    解决方法：LANG=zn jupyter lab。

  • 问题现象：出现报错$ jupyter nbextension enable --py --sys-prefix widgetsnbextension Enabling notebook extension jupyter-js-widgets/extension... - Validating: problems found: - require? X jupyter-js-widgets/extension，如何处理？

    解决方法：jupyter nbextension install --py widgetsnbextension --user和jupyter nbextension enable widgetsnbextension --user --py。

  • 问题现象：出现报错ValueError: Please install nodejs >=12.0.0 before continuing. nodejs may be installed using conda or directly from the nodejs website.，如何处理？

    解决方法：conda install nodejs。关于安装Conda请参考Conda官方文档。

  • 问题现象：安装Sparkmagic时报错失败，如下图所示，如何处理？报错截图

    解决方法：安装Rust。

  • 问题现象：无法使用matplot进行绘图, 即使加入了%matplotlib inline仍然会报错如下图所示。

    matplot报错示意图

    解决方法: 当使用云端PySpark时, 使用%matplot plt组合plt.show()绘制图表, 效果如下图所示。

    matplot正确用法